stat: illegal option -- c on Mac: 13 Letters Change Meaning

On a Mac, stat -c %s file prints stat: illegal option -- c, a one-line usage block, and exits 1. The common fix is to swap -c for -f, because that is macOS's format flag. That swap is the risky part. The format letters are not a shared alphabet. %a, %Y, %z and ten others are valid on both systems, exit 0 on both, and return different values.

I ran 29 format letters through /usr/bin/stat -f on this Mac mini (macOS 26.4.1) and through gstat -c from GNU coreutils 9.12 on the same 12-byte file. 7 matched. 9 failed loudly on the Mac with bad format. 13 printed something else and exited 0.

Why -c is illegal on a Mac

macOS ships the FreeBSD stat. Its format option is -f format, and the FreeBSD stat manual defines its own letter set, taken from the struct stat field names. GNU's -c/--format uses a different letter set. Long options fail on the Mac too: stat --format=%s gives illegal option -- -. That turns out to be handy, because stat --version is a clean way to tell which stat you have.

The loud error is not the problem. It stops the script and names the flag. The trouble starts when someone fixes it by changing one character.

29 letters, run on both

The 13 in the bottom row are the ones worth memorising. The worst five, from the probe output:

Letter	GNU -c printed	Mac -f printed	What the Mac value is
%a	640	1788233445	access time, epoch seconds
%Y	1788233445	(empty)	symlink target; blank for a regular file
%z	2026-09-29 21:01:31.7… +0900	12	size in bytes
%m	/	1788233445	modification time, epoch seconds
%n	f.txt	a bare newline	newline character, not the file name

%Y is the one I would worry about most. GNU scripts use stat -c %Y for "modified how many seconds ago" checks everywhere. Translate it to stat -f %Y and every regular file returns an empty string with exit 0. In a shell arithmetic context that empty string becomes 0, so every file looks 56 years old, and a job that deletes files older than a week treats all of them as expired. %a is the other quiet one: a permission check that expects 640 gets a ten-digit timestamp, and any comparison against it simply never matches.

Two more behaviours from the same run. A bad letter in the middle of a format string does not stop the good ones before it: stat -f 'size=%z user=%U' f.txt wrote size=12 user= to stdout and then exited 1. A script that ignores the exit code keeps the half line. And the Mac usage line mentions none of this; it only lists the flags.

The fallback idiom has a direction

Portable scripts often try one syntax and fall back to the other. Order matters, and only one order is safe:

# GNU first: safe on both
size=$(stat -c %s "$f" 2>/dev/null || stat -f %z "$f")
# Mac:   -c is illegal, exits 1 with nothing on stdout, fallback runs → 12
# Linux: -c works → 12

# Mac first: breaks on Linux
size=$(stat -f %z "$f" 2>/dev/null || stat -c %s "$f")
# Linux: -f means --file-system; "%z" is read as a second file name

I ran the second form with gstat standing in for Linux. GNU treated -f as --file-system, printed five lines of APFS block and inode counts for f.txt to stdout, complained that it could not read a file called %z, and exited 1. So the fallback ran too, and $size ended up holding the filesystem dump followed by 12. The Mac form of the error is harmless because BSD rejects -c before printing anything. The GNU form is not, because -f is a real flag there.

If you would rather branch once than chain, stat --version >/dev/null 2>&1 succeeds on GNU and fails on the Mac. I checked both.

A translation table that I checked

Each pair below gave the same output on the test file, except file type, where only the capitalisation differs (Regular File against regular file). The combined line, stat -f '%z %m %OLp %Su' against gstat -c '%s %Y %a %U', printed 12 1788233445 640 sg-mini on both.

You want	GNU (Linux)	BSD (macOS)
Size in bytes	stat -c %s	stat -f %z
Mtime, epoch	stat -c %Y	stat -f %m
Mtime, formatted	date -r f +%F	stat -f %Sm -t %F
Octal permissions	stat -c %a	stat -f %OLp
Symbolic permissions	stat -c %A	stat -f %Sp
Owner name / group name	stat -c '%U %G'	stat -f '%Su %Sg'
Owner uid / gid	stat -c '%u %g'	stat -f '%u %g' (same)
Hard links	stat -c %h	stat -f %l
File type	stat -c %F	stat -f %HT
Inode	stat -c %i	stat -f %i (same)

For permissions, a 2026 issue in a small project, paynani #80, got a teammate to run both %OLp and %Lp on a real Mac. Both printed 644. They picked %OLp because O asks for octal explicitly, and I agree. Two non-stat traps from the same probe: wc -c < file on the Mac printed 12 with six leading spaces, so a string comparison with "12" fails, and date -r file only covers mtime.

Where I hit it: a file name, not a flag

My own session logs have this error twice outside of probes, and neither was about -c. On 9/4 and 9/11 two of my census loops ran stat -f %Sm -t %Y-%m-%d "$f" over Claude Code transcript files. Those files live under directories named like -Users-sg-mini-GitHub-mmm, the relative paths began with a dash, and stat read -Users… as options: stat: illegal option -- U, once per file. The loops kept going and printed every row with a blank date. The fix is stat -f … -- "$f", which I confirmed on a test file named -Users-x.jsonl. The general version of that bug is in file starting with dash.

265 GitHub threads, half of them this year

I pulled every GitHub issue and pull request that contains the exact string stat: illegal option -- c in its title, body or comments: 265 across 223 repositories, going back to 2009. From 2017 to 2025 the count held between 9 and 16 a year. 2026 has 123 so far, and 87 of those are from August and September alone.

Period	Threads
2009 to 2016	36
2017 to 2025 (9 years)	106
2026, Jan to Jul	36
2026, Aug 1 to Sep 29	87

92 of the 123 from 2026 are pull requests. 58 of the 123 name an AI coding tool in the title or body (Claude 48, Codex 12, Cursor 8, Copilot 4); in the 142 earlier threads it is 3. That is a keyword match, not a reading of each one, so treat it as a direction. My reading of the direction: agents write GNU stat by default, CI runs on Linux and passes, and the break shows up when someone runs the script on a Mac. The older threads look the same without the agent. sdkman-for-fish got a fix PR in July 2019 that was never merged, then issue #30 (macOS 10.14.6) a month later and #31 a month after that, and Envoy PR #23832 (2022) fixed its Docker wrapper for Mac users and was backported to two release branches.

What I do now

• In a script that must run on both, python3 -c 'import os,sys; print(os.stat(sys.argv[1]).st_size)' "$f". The field names don't depend on the platform.
• If it stays in shell: GNU form first, BSD form in the fallback, never the reverse. Or branch once on stat --version.
• Never translate by changing -c to -f and keeping the letter. Look up the letter. Anything in the bottom row of the chart will pass tests that only check the exit code.
• -- before the file name whenever the name comes from a glob or a variable.

This is the same family as date: illegal option -- d on Mac, xargs on macOS and sed invalid command code: the command exists on both systems, so the Linux habit runs, and it only fails loudly some of the time.

Sources: the 29-letter comparison and every command result above were run on 2026-09-29 on a Mac mini (macOS 26.4.1) against /usr/bin/stat and gstat from GNU coreutils 9.12 (Homebrew), on one 12-byte regular file with mode 640 and a fixed mtime; gstat stood in for Linux in the fallback test. Letter meanings are from the FreeBSD and GNU manuals linked above. The GitHub count is a gh api search/issues query for the quoted string in titles, bodies and comments, all 265 results fetched on the same day; the AI-tool figure is a keyword match on titles and bodies only. The two incidents come from parsing tool results in my own session logs, with probe sessions excluded.