exec format error on macOS - ELF never runs here
macOS is not a Linux with a different skin: its executables are Mach-O, and the kernel
has no ELF loader at all. Once you know that, every exec format error on a Mac falls into
one of two buckets, and the fix is different for each.
Bucket 1: you are trying to run a Linux binary natively
$ file ./app
ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked
$ ./app
-bash: ./app: cannot execute binary file
The wording varies — some shells and wrappers say exec format error, some say
bad CPU type in executable — but the cause is the same: Darwin cannot exec an ELF file.
It is not an architecture problem you can solve by getting a different build of the same
binary; there is no "macOS build" of a Linux ELF, because it would not be ELF.
Rosetta 2 does not change this. Rosetta translates x86-64 Mach-O to ARM64 Mach-O. It has no ELF support, so it cannot run an x86-64 Linux binary either — which surprises people who assume "my Mac already emulates x86".
Options, honestly ranked:
| Need | Do this |
|---|---|
| Run a Linux tool occasionally | A container (docker run --rm -it -v "$PWD":/w -w /w ubuntu) |
| Run it regularly | A Linux VM (Lima, UTM, OrbStack) |
| Only need the data it produces | Look for a native build, or a Homebrew formula |
Bucket 2: Docker on a Mac, which is where this actually bites
Docker Desktop on macOS runs a Linux VM. Inside that VM the rules from Linux apply — so
exec format error here means the container's architecture does not match the VM's, exactly
as on any Linux host.
$ docker run --rm --platform linux/amd64 alpine uname -m
exec /bin/uname: exec format error # when no x86-64 handler is registered
Docker Desktop usually registers one for you (Rosetta on Apple Silicon, qemu otherwise), which is why the same command often works on a Mac and fails in CI. When it works on your laptop and fails in the pipeline, the laptop was emulating and the pipeline was not.
On a plain Linux host the same failure and the same fix are measurable:
$ docker run --rm --platform linux/arm64 alpine:3.20 uname -m
exec /bin/uname: exec format error
$ docker run --privileged --rm tonistiigi/binfmt --install arm64
$ docker run --rm --platform linux/arm64 alpine:3.20 uname -m
aarch64
The production bug hiding behind this
The expensive version is not "my container will not start on my Mac". It is:
# on an Apple Silicon Mac, no --platform
docker build -t myapp:1.4 .
docker push myapp:1.4
# ...and every x86-64 server in production fails at startup
The build succeeded, the push succeeded, the tag looks normal — and the image is arm64.
Servers pull it, and their kernel refuses the entrypoint. Nothing warns you, because
architecture is not in the tag.
Check any tag before deploying:
docker manifest inspect myorg/myapp:1.4 | grep architecture
"architecture": "arm64",
Fix: always pass the platform explicitly when the target is not your laptop.
docker buildx build --platform linux/amd64 -t myapp:1.4 --push .
# or publish both and stop thinking about it
docker buildx build --platform linux/amd64,linux/arm64 -t myapp:1.4 --push .
Triage on a Mac
file ./thing # Mach-O? ELF? which machine?
uname -m # arm64 on Apple Silicon, x86_64 on Intel
docker image inspect <img> --format '{{.Architecture}}'
docker manifest inspect <img> | grep architecture
| What you see | Meaning | Fix |
|---|---|---|
ELF ... and you ran it directly |
Not runnable on macOS, ever | Container or Linux VM |
Mach-O ... x86_64 on Apple Silicon |
Needs Rosetta (usually automatic) | Install Rosetta, or get the arm64 build |
Mach-O ... arm64 on Intel Mac |
Built for the wrong CPU | Get the x86_64 build |
Container fails with exec format error |
Image arch ≠ Linux VM arch | --platform, or a multi-arch image |
exec /bin/sh: no such file or directory |
Loader missing (glibc on Alpine) | Rebuild on the right base image |
Note the last row: that one is not an architecture problem, and --platform will not fix
it.
The one-line habit
Before running anything you did not compile locally:
file ./thing | grep -q ELF && echo "Linux binary - needs a container or VM"
And before pushing an image that will run somewhere else:
docker buildx build --platform "<target>" ...
Two habits, and this error stops appearing in your week.
For reading the binary's header — machine type, class, static or dynamic — paste it into ELF Inspector; it runs in the browser and uploads nothing.
macOS behaviour described here follows from the platform's Mach-O-only executable format; the ELF rejection and the Docker/qemu measurements were reproduced on Linux (Docker 29.1.3, kernel 7.0 x86-64), which is the same kernel path Docker Desktop runs inside its VM.