date: illegal option -- d on Mac: 6 Wrong Dates, Exit 0

On a Mac, date -d yesterday prints date: illegal option -- d, the usage block, and exits 1. That part is easy. Every answer to the error says the same two things: install GNU coreutils and call gdate, or translate to the BSD flags -v, -j and -f. The error is the good outcome. It tells you the command failed.

The translation is where it goes wrong quietly. I ran 61 BSD date command lines on this Mac mini (macOS 26.4.1, /bin/date) and the matching cases through gdate from GNU coreutils 9.12. Six BSD forms printed a wrong or surprising date and still exited 0. One GNU form did the same. Nothing in the output marks any of them.

Why -d is illegal on a Mac

macOS ships the FreeBSD date, not the GNU one. The local man page's history section says -d used to exist there with a different meaning, "set DST flag", and was removed. GNU's -d STRING and every long option (--date, --version) hit the same getopt wall: illegal option -- - for the long ones, which is why date --version is not a way to tell which date you have. The usage line it prints is the useful part. On 26.4.1 it lists -I, -z output_zone and -r filename|seconds, which older answers do not know about.

Here is the translation table, with each BSD command run on this machine and the GNU form run through gdate:

You want	GNU (Linux)	BSD (macOS)
Yesterday	date -d yesterday +%F	date -v-1d +%F
Epoch to date	date -d @1790000000	date -r 1790000000
File mtime	date -r file	date -r file (same)
Parse a string	date -d 2026-09-01 +%s	date -j -f "%F %T" "2026-09-01 00:00:00" +%s
ISO 8601	date -Iseconds	date -Iseconds (same)
Output in UTC	date -u	date -u or date -z UTC
Next Monday	date -d "next monday"	date -v+mon
Nanoseconds	date +%s%N	date +%s%N (same)

The parse row is longer than it looks necessary, and the reason is trap two below.

Six BSD answers that exit 0 and are wrong

1. Flags after the date string are ignored

BSD date stops reading options at the first operand. date -j -f %F 2026-01-31 -v+1m +%F printed Sat Jan 31 10:31:23 KST 2026. Both the adjustment and the output format were dropped, exit 0. Swap the last two words and you get 2026-01-31, with only the -v dropped. Moving -v+1m in front of -f gives the intended 2026-02-28. GNU tutorials put flags anywhere because GNU getopt permutes arguments; the Mac binary does not.

2. -f fills the missing fields from right now

date -j -f %Y-%m-%d 2026-09-01 +%s returned 1788226281. Midnight on that day in my zone is 1788188400. The difference is 37,881 seconds, which is 10:31:21, the wall-clock time when I ran it. Two seconds later the same command returned 1788226283. The man page says only that parsing uses strptime(3); in practice any field the format leaves out keeps the current value. If you compare two parsed dates in one run, the offsets cancel. If you store one, it drifts with the hour the script happened to run. Give every field: -f "%F %T" "2026-09-01 00:00:00".

3. February 30 becomes March 2

date -j -f %F 2026-02-30 +%F printed 2026-03-02, exit 0. Day 32 is rejected with illegal time format, so the parser checks the range 1 to 31 and then lets the calendar roll over. gdate -d 2026-02-30 returned invalid date '2026-02-30', exit 1. If a date comes from user input or a config file, BSD date is not a validator.

4. -z changes the output zone, not the input

date -j -z UTC -f "%F %T" "2026-09-01 00:00:00" "+%F %T %Z" printed 2026-08-31 15:00:00 UTC. The input was read as Seoul time and converted. -u in the same place printed 2026-09-01 00:00:00 UTC. If the string you are parsing is already UTC, as most API timestamps are, -u is the flag you want.

5. Month math clamps instead of overflowing

BSD -v+1m on January 31 gives 2026-02-28, and -v-1m on March 31 also gives 2026-02-28. The man page documents this: when the target month is shorter, "the last day of the target month will be the result". GNU does the opposite. gdate -d "2026-01-31 +1 month" returned 2026-03-03, and "2026-03-31 -1 month" returned 2026-03-03 too, meaning one month back landed three days forward. The GNU manual uses its own example, 2022-12-31 -1 month giving 2022-12-01, and I got exactly that. Neither behavior is a bug. The trap is porting a script and assuming the two agree at month end.

6. A time that does not exist is moved forward

With TZ=America/New_York, 02:30 on 2026-03-08 falls in the daylight saving gap. BSD date printed 2026-03-08 03:30:00 EDT and exit 0. gdate refused with invalid date. Across that same gap, -v+1d from noon keeps noon (12:00:00 EDT) while -v+24H gives 13:00:00 EDT. The man page explains both rules: units larger than hours ignore DST, hours and smaller honor it.

The GNU trap: +1 after a time is a timezone

Installing coreutils does not make you safe either. gdate -d "2026-09-29 10:00:00 +1 day" returned 2026-09-30 18:00:00 KST, not 10:00. GNU reads +1 right after a time as a zone correction of UTC+1. The time-of-day section of the manual says so: "the one- or two-digit correction is interpreted as a number of hours." So the parser read 10:00 at UTC+1, which is 18:00 in Seoul, and then added a day. "2026-09-29 +1 day" with no time is fine, and so is "2026-09-29 10:00:00 1 day" without the sign.

Errors that at least exit 1

Three more cases fail loudly, but the message points somewhere else. %z on this Mac accepts +0900 and rejects +09:00, which is the form date -Iseconds itself prints. Feeding date its own output back failed with illegal time format; stripping the colon made it parse. Using -f without -j tells date to set the clock. As a normal user that ends in date: clock_settime: Operation not permitted. Under sudo it would change the system time. Finally, %a and %b are locale-dependent. Under LC_ALL=ko_KR.UTF-8 a plain Tue, 29 Sep 2026 string failed to parse. It worked with LANG unset, which is how my scheduled jobs run.

What my own agents actually wrote

I run this business with scheduled coding-agent sessions on this Mac, so I checked the last 30 days of session transcripts, parsing tool results rather than grepping raw text. There were 1,077 shell commands containing date. Of the invocations, 1,594 used no flag except a +format, 31 used -u, 5 used -v and 3 used -j -f. GNU -d appeared only inside grep patterns. Exactly one result contained illegal option, and it was a search query string, not a date run. The agents mostly avoided the problem by doing date arithmetic in Python.

The ops tree has two scripts that do date math in shell. One uses date -v+1d and is fine. The other parses a stored refresh date with date -j -f "%Y-%m-%d" "$LAST" "+%s" 2>/dev/null || echo 0 and then only warns when the result is greater than 0. Trap two is harmless there, because it subtracts two values filled with the same time of day. The fallback is the problem. A parse failure turns into 0, and 0 turns off the 30-day stale-token warning without a sound. That is the same failure shape as a pipe hiding an exit code: an error converted into a value that looks like "nothing to report."

What I use now

• BSD date for display and simple offsets: -v flags before everything else, format last.
• For parsing, every field in -f, -u when the input is UTC, and LC_ALL=C if names of days or months are involved.
• If a script must match Linux output, call gdate by name. It is 15 MB and does not replace /bin/date unless you add its gnubin directory to PATH.
• Anything that validates or compares dates goes to Python, where 2026-02-30 raises an error.

This is the same family as sed invalid command code, timeout command not found on Mac and the macOS rsync version: the command name exists, so the GNU habit runs, and the divergence shows up somewhere else. With date, the loud error is the easy half.

One correction to older answers: the most-voted Stack Overflow question on Mac versus Linux date, Date command does not follow Linux specifications (41,998 views), has an answer saying the Mac date "doesn't go beyond one second". That is out of date. %N works on 26.4.1; the man page says it arrived in FreeBSD 14.1. In five runs the last three digits were always 000, so the resolution here is microseconds. gdate +%N showed the same trailing zeros, so the limit is the clock call, not the tool.

Sources: every command result here was measured on 2026-09-29 on a Mac mini (Mac16,10, macOS 26.4.1 build 25E253) against /bin/date and gdate from GNU coreutils 9.12, installed with Homebrew for the comparison; TZ was the system default (Asia/Seoul) except where TZ=America/New_York is shown. Flag semantics come from the local date(1) man page, cross-checked against the FreeBSD date manual and the GNU coreutils manual pages linked above. The transcript counts come from parsing tool calls and results in my own session logs (30-day retention, probe sessions excluded). Stack Overflow view counts are from the Stack Exchange API on the same day; the canonical error question is this one (23,594 views).