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

exec format error in Docker - measured, with the fix that works

2026-11-15 By luckyray Docker 29.1.3 - kernel 7.0 x86-64 - alpine:3.20

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.

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