guides / mac-exec-format-error troubleshootingupdated 2026-11-15 readelf -h ./app

exec format error on macOS - ELF never runs here

2026-11-15 By luckyray Docker 29.1.3 - kernel 7.0 x86-64 repro

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.

Related

guides
  1. glibc and libstdc++ versions by distribution — measured, not remembered
  2. version `GLIBCXX_3.4.29' not found — and why copying libstdc++ does not fix it
  3. ldd: not a dynamic executable — what it means (nothing is broken)
  4. bash: cannot execute binary file - what bash actually checked
  5. node: cannot execute binary file - the four ways Node breaks
  6. openshift-install: cannot execute binary file - wrong CPU
  7. exec format error in Docker - measured, with the fix that works
  8. exec format error on Raspberry Pi - 32-bit binary, 64-bit OS
  9. exec format error on ECS / Fargate - task and image disagree
  10. exec format error in WSL - which of the two directions you are in