base64 on Mac: Unpadded Input Loses Bytes, Exit 0

Paste the sample token from jwt.io into the usual one-liner on a Mac and this is what comes back:

$ echo "$JWT" | cut -d. -f2 | base64 -d
{"sub":"1234567890","name":"John Doe","iat":1516239022
$ echo $?
0

The closing brace is gone. Pipe it into jq and you get parse error: Unfinished JSON term at EOF at line 1, column 54, which points at the JSON, not at base64. GNU coreutils 9.12 decodes the same 75 characters into all 55 bytes.

I ran macOS base64 and GNU's through the same inputs on this Mac mini (macOS 26.4.1). There are two problems that matter. Input without = padding loses its last one to three characters and still exits 0. And every GNU-style call that names a file fails with exit 64. The rest are smaller differences, listed in the chart.

What /usr/bin/base64 is

It's FreeBSD's bintrans program. The 136,480-byte binary has four hard links, and /usr/bin/uudecode is one of them. base64 --version prints FreeBSD base64 to stderr. Apple publishes it in text_cmds. The bintrans directory first appears in text_cmds-165, the version macOS 14 ships, so everything below applies to Sonoma and later. Reports from macOS 13 show a different usage line, [-hDd] instead of today's [-Ddh].

Apple didn't take FreeBSD's version as is. In bintrans.c, an #ifdef __APPLE__ block keeps the old Mac interface: -i means input file, -o means output file, -D still decodes, output isn't wrapped "for compatibility", and any leftover argument is an error. FreeBSD's own branch of the same file takes a file operand like GNU does.

Trap 1: unpadded input loses its tail, exit 0

The shortest case is two letters. printf hi | base64 gives aGk=. Drop the =:

$ printf 'aGk' | base64 -d | wc -c
       0
$ printf 'aGk' | gbase64 -d
hi

The decoder in uudecode.c works in complete groups of four characters. Whatever is left after the last full group is carried over to be joined with the next line. At end of input there is no next line, so the carry-over is dropped and the function returns success. One leftover character can't be valid base64, but two or three can, and they're simply lost. In my tests no bytes were lost when the input was padded, and round trips of 1 byte to 1 MiB came back identical.

Unpadded base64 isn't rare. JWTs leave the padding off by design (RFC 7515 §2), and so do many URL tokens and API keys. Two out of every three payload lengths need padding, so most hand-decoded tokens on a Mac come back short. The jwt.io sample is 75 characters, 3 past a multiple of 4, which is how it lost its last byte.

GNU used to fail on this too, but loudly. Coreutils 9.5 (NEWS, 2024-03-28) says base64 "no longer require[s] padding when decoding. Previously an error was given." So a Linux box on 9.4 or older prints invalid input and exits 1, a current one decodes the whole thing, and the Mac returns fewer bytes with exit 0. Only the Mac gives a wrong answer without any error.

Trap 2: file arguments are rejected

$ base64 notes.txt
base64: invalid argument notes.txt
Usage:	base64 [-Ddh] [-b num] [-i in_file] [-o out_file]
$ echo $?
64

Same for base64 -d file.b64 and for - as stdin, which GNU accepts and the Mac treats as a stray argument. At least this one is loud. The catch is -i. In GNU, base64 -di means decode and ignore garbage. On the Mac -i takes a file name, so -di fails with option requires an argument -- i, and -d -i data.b64 works by accident.

Three rows go the other way, where the Mac is the more forgiving one. It decodes the URL-safe alphabet (- and _) because Apple added that to the decoder, so on the Mac you don't need tr '_-' '/+' before decoding a JWT. GNU wants it, or basenc --base64url. The Mac also skips carriage returns and spaces, which GNU rejects. But it refuses two padded strings joined end to end (aGVsbG8=aGk=), which GNU decodes as both. And input like not base64!! decodes to six junk bytes with exit 0, where GNU stops with an error.

Encoding differs only in layout. The Mac writes one unbroken line by default, GNU wraps at 76 characters. To match, pass -b 76 on the Mac (byte-identical to GNU's default in my test) or -w 0 to GNU. The Mac also accepts -w and --wrap, though its usage text doesn't list them.

43 GitHub reports of the loud one

I searched GitHub issues and PRs for "base64: invalid argument" on 2026-10-01 and fetched all 372 results. 43 quote the error in the title or body. The rest match only in comments or on the words alone, and I didn't read those. The 43 come from 35 repositories, and 16 are from 2026.

What the Mac rejected	Reports
A file operand (base64 file, base64 -d file)	31
--output (macOS 13, usage line [-hDd])	6
- for stdin	3
-w0 or --w (older macOS)	2
Screenshot only	1

The file operand is three quarters of it. One repository, tangle-network/agent-app, has six PRs that each record the same local test failure (#415 is one) as pre-existing and unrelated. Their code shells out to base64 -d <file>, and their CI runs on Linux. moj-cli #1 shows the cost under set -euo pipefail: the CLI dies with rc 64 before it makes a single network call.

Two PRs in one repo get the cause wrong. watermarks-remover #119 says "On macOS/BSD there is no -w flag" and quotes base64 -w0 notes.md failing. But the error names notes.md, not -w0, and printf hi | base64 -w0 works on 26.4.1. The flag is fine; the file name is the problem. The same mistake showed up when I went through sha256sum on Mac threads: people blamed the flags when the real difference was how input is read.

None of the 43 is about the silent truncation. That fits, since you only get a report when something prints an error, and trap 1 doesn't print one.

What I use now

For whole files, the form that works on both:

base64 < in.bin | tr -d '\n' > out.b64   # encode, one line on both
base64 -d < in.b64 > out.bin            # decode

For anything that might be unpadded or URL-safe, pad it yourself before decoding:

#!/bin/sh
# b64url_decode: base64 or base64url on stdin, decoded on stdout
s=$(tr -d ' \r\n' | tr '_-' '/+')
case $(( ${#s} % 4 )) in
  2) s="$s==" ;;
  3) s="$s=" ;;
  1) echo "b64url_decode: invalid length" >&2; exit 1 ;;
esac
printf '%s' "$s" | base64 -d

I ran it with PATH pointing at the Mac base64 and then at GNU's. Both decoded the jwt.io header and payload in full, and both rejected a five-character input with exit 1. The tr '_-' '/+' line is only needed on GNU, but leaving it in keeps one script for both.

If you're writing a check, compare the byte count you expect with what you got. Exit 0 from Mac base64 -d doesn't mean every byte was decoded. That's the same lesson as sha256sum -c and date on a Mac, where the wrong answer also exits 0. For other GNU habits that macOS reads differently, see xargs on macOS and stat: illegal option -- c.

Update, 2026-10-01: head has the same split. Mac head -n -1 and head -n 0 fail with illegal line count, while Mac tail -n 010 quietly returns 8 lines because it reads the count as octal. The side-by-side runs are in head: illegal line count on Mac.

Sources: every output and exit code above was run on 2026-10-01 on a Mac mini (macOS 26.4.1, build 25E253) against /usr/bin/base64 and gbase64 from GNU coreutils 9.12 (Homebrew), which stood in for Linux. Source lines are from Apple's text_cmds-197 (bintrans.c, uudecode.c, apple_base64.c), and the macOS 14 start date comes from the first text_cmds tag that contains bintrans. The macOS 13 behavior is from users' reports, including github/docs #22970, not my own test. GNU's padding change is quoted from its NEWS file and the options from the coreutils manual. The GitHub counts come from gh api search/issues, and I classified each report by reading its title and body.