DEV Community

Weifeng Liu
Weifeng Liu

Posted on Originally published at readelf.com

Docker's exec format error, measured before and after registering qemu

exec format error in Docker — measured, including the fix that actually 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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",
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

/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 .
Enter fullscreen mode Exit fullscreen mode

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 .
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (1)

Collapse
 
c-wind profile image
c-wind •

The before/after measurement is the part that usually gets skipped in these write-ups, and it makes the diagnosis actually checkable. One thing that bit me after doing the same tonistiigi/binfmt --install: the handlers live in binfmt_misc, which is not durable across a reboot unless something registers them again (a privileged binfmt container with a restart policy, or the distro qemu-user-static package). Worth a quick ls /proc/sys/fs/binfmt_misc/ the next morning before you assume a previously working --platform linux/arm64 run has suddenly broken.

Also useful: after install, check that the qemu-aarch64 entry has the F (fix-binary) flag. That opens the interpreter on the host so it stays reachable from inside the container's mount namespace. A registration without F can look fine in /proc and still fail at docker run.