head: illegal line count on Mac: Why -1 and 0 Fail

There is a line in one of my own research logs that I didn't notice for 20 days. On September 11 I was mapping launchctl Load failed: 5 causes, and line 3 of the saved matrix log reads:

=== [01-load-ok] launchctl load /tmp/lcprobe/c01.plist
rc=0
head: illegal line count -- 0
print: loaded

The probe script had launchctl print gui/501/... | head -0 in it. I wanted the output thrown away, and head -0 was my shorthand for "print zero lines". GNU head does exactly that. The head that ships with macOS refuses the count, prints the error, and exits 1. The output was discarded anyway, because head quit before reading it, so the run looked fine. The only evidence was that stray line, and it went into the research folder along with everything else.

Today I went back and ran Mac head and tail against GNU coreutils 9.12 on this Mac mini (macOS 26.4.1), read Apple's source, and collected all 181 GitHub issues and PRs that quote the error. Here is what the message means, why it's usually -1 or 0, and what to use instead.

What "illegal line count" means

Mac head accepts a positive decimal whole number for -n, and nothing else. In Apple's head.c the check is two lines: parse with strtol(optarg, &ep, 10), and if anything is left over or the result is <= 0, exit with illegal line count -- %s. The -c option does the same thing and prints illegal byte count.

That is what POSIX asks for. The POSIX head page says the option-argument "is a positive decimal integer." GNU goes further. Its manual says that if the number starts with -, head prints "all but the last num lines," and it also accepts 0 and suffixes like 1k. Scripts written on Linux use those extensions without knowing they are extensions, and the Mac rejects them:

$ printf 'a\nb\nc\n' | head -n -1
head: illegal line count -- -1
$ echo $?
1
$ head -n 0 notes.txt
head: illegal line count -- 0
$ head -n 1k big.log
head: illegal line count -- 1k

One thing to know if you test this from zsh: if the count is stored in a variable like a="-n -1" and you pass it unquoted, zsh doesn't split it, so head receives "-n -1" as one argument and the message has two spaces: --  -1. Same error, different-looking text. I ran the probes below in bash 3.2 to avoid that.

Mac tail parses numbers differently from Mac head

I expected tail to follow the same rules. It doesn't. Apple's tail.c parses its count with expand_number(), which accepts octal, hex, and size suffixes. So the two tools that come with the same OS read the same string differently:

The tail -n 010 row is the dangerous one, because it doesn't fail. A count that came out of printf '%03d' or date +%m keeps its leading zero, and Mac tail reads it as octal. 010 gives 8 lines, 08 and 09 fail with illegal offset -- 08: Invalid argument, and 01 to 07 happen to be right. Mac head parses base 10, so head -n 010 gives 10. FreeBSD's own head.c uses expand_number() too, so Apple's head is the one that went its own way. I didn't test FreeBSD itself.

181 reports, half of them from 2026

I searched GitHub for "head: illegal line count" in titles, bodies, and comments and got 181 results, all collected (the API reported the result set as complete). That's 105 PRs and 76 issues. 90 are from 2011 through 2025. 91 are from 2026, with a peak of 19 in August. In 46 of the 91 from 2026, the title or body mentions Claude, Codex, Cursor, Copilot, GPT, or Gemini. That's a keyword match, not proof of who wrote the script, but it fits: an agent writes the shell it knows from Linux training data, and nobody runs it on a Mac until later.

I pulled the count value out of each report. 112 quote a negative count, and -1 appears in 85 of them. 15 quote zero. 7 quote something else (notanumber, 100000b, =1, file paths from broken arithmetic). 47 don't include the full message in the text I could parse.

The -1 reports are nearly all doing one thing: dropping a trailing line, whether that's a closing marker, the last line of a help block, or the status code from a curl call that ends with -w '\n%{http_code}'. OpenRouterLabs/spawn #339 is a clean example. response_body=$(echo "${response}" | head -n -1) came back empty on macOS, so every Fly.io API call then failed with JSONDecodeError, which points at the JSON and not at head. Release scripts trimming a changelog section are another, as in apache/skywalking-java #818.

The zero reports are harder to catch, because the count is computed and is only 0 sometimes. yotamleo/Himmel #1451 describes it exactly: BSD head rejects -n 0, "which is exactly the call when the wired block is at line 1." The script works for every file except the ones where the marker is on the first line. wpf002/flint #32, opened today, lists a "head -n 0 offsite-prune bug" on macOS as a P0 for a backup tool.

Why it gets missed

Whether you see the failure depends on where head sits in the pipeline. If head is last, the exit status is 1 and set -e stops the script, as with x=$(... | head -n -1). If anything comes after head, the pipeline's status belongs to that later command:

$ bash -c 'set -e; printf "a\nb\n" | head -n -1 | wc -l; echo still running'
head: illegal line count -- -1
       0
still running

That's the same exit-status masking I wrote up in the pipe exit code post. iamcxa/kc-claude-plugins #270 found the test-suite version of it: putting the GNU-only line back "passed every check, because its only trace was head: illegal line count -- -20 on a stream the test discarded." They fixed it by making the suite fail on any stderr output. My head -0 survived the same way: the error went to a log nobody read.

What works on both

To drop the last line, sed '$d' works with both BSD and GNU sed. For the last N lines, I use a small awk function that keeps a ring buffer of N lines:

#!/bin/sh
# drop_last N [file]: print all but the last N lines (GNU: head -n -N)
n=${1:?usage: drop_last N [file]}; shift
case $n in ''|*[!0-9]*) echo "drop_last: bad count: $n" >&2; exit 2;; esac
awk -v n="$n" 'n == 0 { print; next }
  NR > n { print buf[NR % n] }
  { buf[NR % n] = $0 }' "$@"

I compared it with ghead -n -N on files of 0, 1, 2, 3, 5, and 50 lines with N set to 0, 1, 2, 3, and 7. All 30 outputs had the same checksum. The one difference I found is with N=0 on a file that doesn't end in a newline: awk adds one and GNU head doesn't.

For the curl split, skip head entirely and use parameter expansion, which works in bash 3.2 and zsh:

r=$(curl -s -w '\n%{http_code}' "$url")
body=${r%$'\n'*}     # everything before the last newline
code=${r##*$'\n'}    # everything after it

For "first N lines" where N might be 0, use awk -v n="$n" 'NR > n { exit } { print }', which prints nothing when N is 0. Don't switch to sed -n "1,${n}p". With n=0 it prints line 1, on BSD sed and GNU sed alike, because a range whose end is before its start still matches its first line. To discard output, which was all I wanted on September 11, redirect it: >/dev/null.

And if a count might have a leading zero, strip it before it reaches Mac tail: n=$((10#$n)) in bash, or use awk. Installing coreutils doesn't change /usr/bin/head. Homebrew installs ghead and gtail, and plain head stays BSD unless you put the gnubin directory first in your PATH, which then only fixes your own machine. The same kind of difference shows up in base64 on Mac and xargs on macOS.

Update, October 1, 2026: shuf is the coreutils command people most often replace with a pipeline ending in head, usually sort -R | head -1, which is biased on macOS. I tested it and the alternatives in shuf on Mac.

Sources: every command output above was run on 2026-10-01 on a Mac mini (macOS 26.4.1, build 25E253) under bash 3.2.57, against /usr/bin/head, /usr/bin/tail, and ghead/gtail from GNU coreutils 9.12 (Homebrew), which stood in for Linux. The September 11 line is in my own research log for the launchctl post, and the | head -0 call comes from that session's transcript. Parsing details are from Apple's text_cmds-197 source. The FreeBSD claim is from reading its head.c, not from running it. The GitHub numbers come from one gh api search/issues query (181 results, complete). I classified count values with a regex over each result's body and search snippets, and checked the quoted PRs by reading them.