exec format error in Docker - measured, with the fix that works
exec /bin/sh: exec format error from Docker is not a Docker bug and not a broken image. The
image contains binaries for a CPU your kernel is not, and there is no emulator registered to
translate them.
Both directions below were measured on an x86-64 host, Docker 29.1.3, kernel 7.0.
Reproduce it in one command
$ docker run --rm --platform linux/arm64 alpine:3.20 uname -m
exec /bin/uname: exec format error
The image is intact. The pull succeeded. --platform asked Docker for the ARM build of the
image, and this kernel cannot execute ARM instructions — no handler is registered in
binfmt_misc, so execve() fails with ENOEXEC and Docker surfaces it as
exec format error.
Check whether you have any foreign-arch handlers at all:
$ ls /proc/sys/fs/binfmt_misc/
python3.14 register status # no qemu-aarch64 -> ARM images cannot run here
On a machine with emulation installed you would see qemu-aarch64, qemu-arm, etc.
The fix that works: register the emulator
$ docker run --privileged --rm tonistiigi/binfmt --install arm64
$ docker run --rm --platform linux/arm64 alpine:3.20 uname -m
aarch64
Measured, in that order. The same command that failed a minute earlier now returns
aarch64. Nothing else changed — no rebuild, no image change.
Remove it again when you are done (the handler is host-wide state):
$ docker run --privileged --rm tonistiigi/binfmt --uninstall arm64
$ docker run --rm --platform linux/arm64 alpine:3.20 uname -m
exec /bin/uname: exec format error # back to the original behaviour
Should you? For a CLI you invoke occasionally, yes. For builds and test suites, yes but expect 5–20× slowdown. For production workloads, no — run the image on hardware of its own architecture instead of paying the emulation tax on every request.
The three places this error appears
1. docker run --platform naming an architecture you cannot execute
Exactly the case above. The platform flag is a request, not a promise: Docker will pull the image and then fail at exec time.
2. An image that only exists for another architecture
$ docker run --rm someorg/arm-only-tool:1.2
exec /app/tool: exec format error
There was no --platform to blame. Check what the image actually offers:
$ docker manifest inspect someorg/arm-only-tool:1.2 | grep -E '"architecture"|"os"'
"architecture": "arm64",
A single-architecture manifest is the answer: this image will never run here.
3. docker build --platform producing an image you cannot run
$ docker buildx build --platform linux/arm64 -t app:arm .
$ docker run --rm app:arm
exec /app/entrypoint: exec format error
The build is correct; the run is on the wrong host. Either push it to a registry and run it where it belongs, or add the emulator as above for a local smoke test.
Distinguish it from the other Docker error
| Message | Real cause |
|---|---|
exec /bin/sh: exec format error |
Architecture mismatch |
exec /bin/sh: no such file or directory |
The loader inside the binary is missing — glibc binary in an Alpine/musl image |
standard_init_linux.go:…: exec user process caused: exec format error |
Same as the first, older Docker wording |
Measured example of the second, where the file demonstrably exists:
$ docker run --rm -v /bin/true:/x/true:ro alpine:3.20 /x/true
exec /x/true: no such file or directory
/bin/true is a glibc binary; Alpine's loader is musl. The file is present — its
interpreter is not. Fixing that is a rebuild (or a static build), not a platform flag.
Practical rules
For images you publish: build multi-arch and let the registry serve the right one.
docker buildx build --platform linux/amd64,linux/arm64 -t you/app:1.0 --push .
Then docker pull you/app:1.0 on any host gets a runnable build with no flags.
For images you consume: prefer the official multi-arch image over a single-arch tag.
alpine, node, python, postgres all publish manifest lists — the platform is chosen
for you.
For CI: pin the platform explicitly, so a runner with a different CPU does not silently change what you build.
docker build --platform linux/amd64 .
For local debugging only: install the emulator, and treat the result as a smoke test — not as evidence about performance.
Verify before you debug further
uname -m # host architecture
docker image inspect <img> --format '{{.Architecture}}' # image architecture
docker manifest inspect <img> | grep architecture # what the tag offers
file ./binary-on-host # the binary itself, if it is on disk
If the two architectures differ and you are not willing to emulate, the fix is a different image — not a different command.
To read the binary's header without running it, drop it into ELF Inspector: machine type, class, and static/dynamic in one view.
Measured on Docker 29.1.3 / kernel 7.0 x86-64 with alpine:3.20, before and after registering qemu-aarch64 via tonistiigi/binfmt. The host was returned to its original state after the test.