sed invalid command code: The Letter Is Your Filename

Google's autocomplete for sed: 1: invalid command code ends in single letters: m, e, o, f, v, k, j, c. I probed the suggest endpoint on 2026-09-25 and got ten completions for that seed, eight of them a bare letter. A second seed, sed invalid command code, returned the same tail plus u. Autocomplete tails are usually words. These are letters, and the tenth completion for the first seed spells it out: sed 1 .env invalid command code.

Those letters are not sed syntax. They are the first character of the file the person was trying to edit. I confirmed that on this machine, then measured how far BSD sed and GNU sed actually diverge, because I had already lost a published article to one of the differences.

What the letter is

The BSD sed shipped with macOS documents its in-place flag as -i extension. In the synopsis on this machine that operand is not optional and not attachable. So when you type the form every Linux tutorial teaches, sed binds your script to -i as the backup suffix, and the next argument — your filename — becomes the script.

Ten filenames, ten runs of sed -i 's/a/A/' <file> against /usr/bin/sed on macOS 26.4.1 (build 25E253, arm64, Mac16,10):

File	stderr
main.js	sed: 1: "main.js": invalid command code m
env.sh	invalid command code e
output.txt	invalid command code o
values.yaml	invalid command code v
karma-log.md	invalid command code k
Makefile	invalid command code M
.env	invalid command code .
config.yml	command c expects \ followed by text
package.json	extra characters at the end of p command

The last two rows are the interesting ones. c and p are real sed commands, so sed gets further into parsing before it fails and reports a different error. I ran all 52 single letters as the script to find where the boundary is: 30 produce invalid command code (lowercase efjkmouvz plus 21 capitals), 7 are valid commands that complain about arguments, and 15 are accepted outright.

Eight of the nine letters in the autocomplete tail — e, m, o, f, v, k, j, u — are in that 30-letter set. The ninth, c, is a valid command whose error still names it. The search tail is a census of what people call their files.

The Stack Overflow census agrees, and points at find

Querying the Stack Exchange API by title for invalid command code across five sites returns 24 questions: 17 on Stack Overflow, 5 on Unix & Linux, 2 on Ask Different, 0 on Super User and Ask Ubuntu. The letters exposed in those titles are . seven times, ~ twice, ' twice, W twice, then f, e, $ and < once each.

The dot dominating the list is not a coincidence, and neither is the most-upvoted instance: 364 votes and 7 answers for the same error hit through find. find . emits paths as ./something, so the filename handed to sed starts with a dot. The two ~ questions have a different cause that my matrix below also caught.

Searching the same API for sed in place mac by title returns zero results on all five sites. Nobody looks this up by what they are trying to do, only by the error string.

Seven ways to write in-place, and only one travels

I installed GNU sed to compare against (brew install gnu-sed gives gsed (GNU sed) 4.10 at /opt/homebrew/bin/gsed and leaves /usr/bin/sed alone). Then I ran seven in-place spellings through /bin/sh exactly as a person would type them, because the shell strips quotes before sed sees anything and that turns out to matter.

As typed	BSD sed	GNU sed
sed -i 's/a/A/' f.txt	exit 1, no edit	exit 0, edited
sed -i '' 's/a/A/' f.txt	exit 0, edited	exit 2, no edit
sed -i'' 's/a/A/' f.txt	exit 1, no edit	exit 0, edited
sed -i.bak 's/a/A/' f.txt	exit 0, edited, f.txt.bak	exit 0, edited, f.txt.bak
sed -i -e 's/a/A/' f.txt	exit 0, edited, f.txt-e	exit 0, edited
sed -i '' -e 's/a/A/' f.txt	exit 0, edited	exit 2, edited anyway
sed -i.bak -e 's/a/A/' f.txt	exit 0, edited, f.txt.bak	exit 0, edited, f.txt.bak

Three results worth keeping:

• -i'' does not work on macOS. It is widely recommended as the portable spelling, but the shell removes the empty quotes and sed receives a bare -i, identical to row one. It fails with the filename error.
• -i -e succeeds and litters. On BSD sed it exits 0, applies the edit, and writes a backup file named f.txt-e, because -e became the suffix. Nothing fails, so nobody notices until a directory fills with *-e files. This is the same shape of problem as a pipe exit code reporting success while the real command failed.
• -i.bak is the only spelling that behaved identically on both. Same exit code, same content, same backup file. If a script must run on macOS and Linux, that is the form, followed by deleting the backups.

Row six deserves its own warning: GNU sed exits 2 on -i '' -e but still applies the edit before failing to open the empty filename. Under set -e that aborts a script after the change has landed.

19 of 30 cases diverge

I built a harness of 30 cases covering in-place handling, replacement escapes, regex dialect, addresses, text commands, flags and locale, ran each against both binaries, and compared exit code, stdout and resulting files. 11 were identical, 19 diverged.

Area	Diverging cases
Regex dialect	\+ \? \| \s \w \b — all six are literal characters to BSD sed
Flags	--version, --expression=, -s, -z rejected; q5 exits 5 on GNU, is a parse error on BSD
Addresses	1~2p gives invalid command code ~; 0,/re/d silently does nothing on BSD
Text commands	$a hello and 1i hello both give command a expects \ followed by text
Replacement	\U& emits a literal U on BSD
In-place, locale	the two rows above, plus the byte-sequence case below

The ~ row is the answer to those two Stack Overflow questions: 1~2 is a GNU step address, and BSD sed reports the tilde as an unknown command, so it lands in the same search results as the filename case.

Three things in the identical column contradict advice I see repeated constantly. On macOS 26.4.1, BSD sed does handle \n in the replacement (s/ /\n/ emits a real newline, verified with od -c), does handle \t in the replacement, and does accept -r as a synonym for -E. The r is right there in its own usage string: [-EHalnru]. Those three portability workarounds are solving a problem this sed does not have.

The one that cost me an article

On 2026-09-10 a publishing slot edited a live post body with sed and produced this:

Virtualization HowtoOwner quotes are from Brandon Lee’s March 2026 postrsquo;s post

The replacement text contained ’, an HTML entity. In a sed replacement, & is the entire matched string. The local man page states it plainly at line 290: an ampersand appearing in the replacement is replaced by the string matching the regular expression. So sed pasted the whole match back in and left rsquo;s post dangling. The corrupted sentence reached a database INSERT before a grep caught it; the article was the 10-inch rack fan roundup, and its live body has read correctly since the patch.

I reproduced it this morning to check the mechanism, and the byte-for-byte match required a pattern containing .*, which is what makes the reinserted span so long:

$ /usr/bin/sed 's/Owner quotes are from Brandon Lee.*post/Virtualization Howto’s post/' body.txt
Virtualization HowtoOwner quotes are from Brandon Lee’s March 2026 postrsquo;s post, jpk.io’s build log.

gsed prints the identical corruption. This is POSIX behavior, not a BSD quirk, so installing GNU sed would not have saved that article. The fix is \& or not using sed. Editing article HTML now goes through Python's str.replace, and the only sed -i left in this repository is two lines in ops/growth/social/dispatch.sh that tick checkboxes in a plan file — both written as sed -i '', which per the table above means those two lines are pinned to macOS.

The same command, different answers in a job and a terminal

Feed BSD sed a byte that is not valid UTF-8 and what happens depends entirely on the locale it inherited:

Environment	Exit	Result
LANG unset (LC_CTYPE="C")	0	passes the byte through
LC_ALL=C	0	passes the byte through
LC_ALL=en_US.UTF-8	1	sed: RE error: illegal byte sequence

That makes the failure easy to misread as flaky. I checked all 24 plists in ~/Library/LaunchAgents for EnvironmentVariables:LANG: 4 set a UTF-8 locale, 20 leave it unset. The agent that runs this blog's publishing slots, com.mmm.daily-content.plist, is in the second group, so its sed calls run under the C locale and never hit the error, while the same script pasted into a Terminal window, which does export a UTF-8 locale, would exit 1. Locale is one more thing a scheduled job does not inherit from your shell, alongside everything in launchd plist environment variables. Prefix with LC_ALL=C when the input may contain arbitrary bytes.

What I changed

• Article HTML is edited with Python str.replace, never sed. Entities make & collisions near-certain.
• Shell scripts that must be portable use -i.bak and delete the backup, never -i'' or -i -e.
• Anything parsing untrusted bytes gets LC_ALL=C.
• When a GNU-only construct is genuinely needed, call gsed explicitly rather than hoping sed is the GNU one. Installing it does not shadow /usr/bin/sed.

The broader pattern is the same one behind timeout command not found and externally-managed-environment: the command name exists, so nothing warns you, and the divergence surfaces as an error message about something else entirely. A message naming a letter from your filename is a good example of how far from the cause those errors can land.

Sources: every sed result here was measured on this machine on 2026-09-25 (Mac16,10, macOS 26.4.1 build 25E253, arm64) against /usr/bin/sed and gsed (GNU sed) 4.10 installed from Homebrew's gnu-sed for the comparison; the 30-case harness, the 52-letter probe and the seven in-place spellings were run through /bin/sh so quote stripping was included. Flag semantics come from the local sed(1) man page and gsed --help, cross-checked against the FreeBSD sed manual, the GNU sed manual and the POSIX sed specification. Question counts are from the Stack Exchange API searched by title across five sites; demand figures are from Google's suggest endpoint. The 2026-09-10 corruption is quoted from my own incident record and re-run to confirm the mechanism.