A container that worked on a colleague’s laptop starts on yours and dies at once:
exec /usr/local/bin/docker-entrypoint.sh: exec format errorOlder Docker releases print the same failure through runc’s init code, without naming the file:
standard_init_linux.go:228: exec user process caused: exec format errorThe message comes from the kernel. When the container starts, the runtime calls execve() on the entrypoint, the kernel inspects the file’s first bytes, and it returns ENOEXEC because it recognises none of the formats it knows how to run. Most of the time that’s because the file is an ELF binary compiled for a different CPU. It’s one of the reasons an image that pulls successfully can still crash-loop in Kubernetes. Keep the full error line, since it names the file the runtime tried to execute. The outputs below were reproduced on Docker Engine 29.7 (Docker Desktop on an arm64 Mac) with alpine:3.20.
What the ELF header tells the kernel
The first bytes of an ELF executable encode its target machine (EM_X86_64, EM_AARCH64 and so on) at a fixed offset. If that value doesn’t match the CPU and no emulator is registered for it, execve() fails with ENOEXEC and the runtime prints exec format error. Nothing is “installed wrong”: the binary is simply compiled for a CPU the machine doesn’t have.
You can watch the kernel do this by copying BusyBox out of the arm64 Alpine image, overwriting the two-byte machine field with a value no emulator handles, and running the result:
$ docker run --rm -v "$PWD/bb-odd":/app/hello --entrypoint /app/hello alpine:3.20
exec /app/hello: exec format errorThree situations produce the error in practice:
- A single-platform image on the other architecture. A CI runner on
linux/amd64pushedmyapp:1.4.2, and an arm64 node pulls and runs it. - Compiled code built on the wrong host. A base image can be multi-platform while the code inside isn’t. A Go or Rust binary built on an arm64 laptop and
COPYed into an amd64 image fails withexec format error. A native Node addon or Python extension of the wrong architecture fails later, when it’s loaded, and on glibc the loader’s message is misleading. An arm64 shared library with its machine field changed to x86-64, loaded with Node’sprocess.dlopeninnode:22-bookworm, fails withcannot open shared object file: No such file or directoryalthough the file is there. - A script with no usable shebang. The kernel runs a script only if it starts with
#!. A script with no shebang line, or one saved with a UTF-8 byte order mark in front of the#!, is neither ELF nor a recognisable script, so it fails the same way.
Don’t jump to case 3 just because the error names a shell script. If an amd64 image runs on an arm64 host with no emulation, the kernel reads the script’s #!/bin/sh line, tries to load /bin/sh, finds an amd64 binary and returns ENOEXEC, and the runtime reports that against the script’s path. Pointing a script’s shebang at the patched binary from above shows it:
$ docker run --rm -v "$PWD/bb-odd":/app/hello -v "$PWD/viaodd.sh":/usr/local/bin/docker-entrypoint.sh \
--entrypoint /usr/local/bin/docker-entrypoint.sh alpine:3.20
exec /usr/local/bin/docker-entrypoint.sh: exec format errorSo the architecture check comes first in every case. Cases 1 and 2 mean the image or something inside it is built for the wrong CPU, while case 3 means the image is right but one file inside it is malformed.
Compare two architectures, then check the script
- Check the daemon:
docker info --format '{{.OSType}}/{{.Architecture}}'printslinux/x86_64orlinux/aarch64. - Check the image:
docker image inspect <image> --format '{{.Os}}/{{.Architecture}}'. - If they differ, rebuild for the host or the deployment target:
docker buildx build --platform linux/amd64 -t <image> . - For Compose or plain
docker build, setDOCKER_DEFAULT_PLATFORM=linux/amd64so every build matches. - If they match, inspect the file the error names: a missing
#!or a BOM before it givesexec format error. (CRLF endings give a different error, covered below.) - On a Mac, remember that Docker Desktop emulates amd64, so a mismatched image can run fine on the laptop and fail on a Linux server.
Host versus image: finding the mismatch
Ask docker info, not only uname -m
uname -m # Linux/macOS host
docker info --format '{{.OSType}}/{{.Architecture}}'On an Apple silicon Mac the first line prints arm64 and the second linux/aarch64: the first describes macOS, the second the Linux VM the daemon runs in. With a remote context (docker context ls) the two can describe different machines entirely, so use the docker info value when you decide what to build or run.
Read the image’s OS and architecture
docker image inspect myapp:1.4.2 --format '{{.Os}}/{{.Architecture}}'linux/amd64The two commands name the same CPUs differently: docker info reports the kernel’s names (x86_64, aarch64) and images use Go’s (amd64, arm64). If the image’s architecture is not the daemon’s under either name, you have found the cause. For a tag in a registry that you haven’t pulled, docker buildx imagetools inspect registry.example.com/myapp:1.4.2 lists the platform of every manifest behind the tag, which tells you whether it’s single-platform or a multi-platform index.
Why Docker Desktop doesn’t show the failure
Docker Desktop registers emulators with the kernel’s binfmt_misc mechanism: Rosetta (when enabled) for x86-64 binaries on Apple silicon, and QEMU for several other architectures. Set the patched BusyBox’s machine field to x86-64 instead of a nonsense value and Rosetta picks it up and complains about the contents (rosetta error: not an x86-64 elf (0xb7)): the kernel handed the file to Rosetta instead of refusing it. A plain Linux server has none of this unless someone installed it, which is why “it runs on my Mac” proves little about an amd64 or arm64 node.
Rebuilding with --platform or as multi-platform
docker buildx build --platform linux/amd64 -t myapp:1.4.2 .--platform sets the target architecture for the build, so every FROM without its own --platform pulls the variant for that target. To make it the default for a session or CI job:
export DOCKER_DEFAULT_PLATFORM=linux/amd64
docker build -t myapp:1.4.2 .Build a multi-platform image once and let each host pull its own variant:
docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.com/myapp:1.4.2 --push .Checking the rebuilt tag locally and in the cluster
After rebuilding, the tag should report the target architecture, and a binary inside it should run on a host of that architecture. Overriding the entrypoint keeps the image’s own entrypoint script out of the check:
docker image inspect myapp:1.4.2 --format '{{.Os}}/{{.Architecture}}'
docker run --rm --entrypoint uname myapp:1.4.2 -mOn an amd64 host the expected output is:
linux/amd64
x86_64In Kubernetes, confirm the Pod stays Running and its logs show real application output instead of the exec line:
kubectl get pods -n shop -l app=myapp
kubectl logs -n shop deploy/myapp --tail=20When the architectures match: shebangs, BOMs and CRLF
If the daemon and the image agree on architecture, look at the first bytes of the file the error names:
docker run --rm --entrypoint sh myapp:1.4.2 -c 'head -c 12 /usr/local/bin/docker-entrypoint.sh | od -c | head -n 1'Here is what three broken versions of a two-line script produce, each mounted as the entrypoint of alpine:3.20:
First bytes (od -c) |
Problem | Error |
|---|---|---|
e c h o h i \n |
no shebang | exec /usr/local/bin/docker-entrypoint.sh: exec format error |
357 273 277 # ! / b i n / s h |
UTF-8 BOM before #! |
exec /usr/local/bin/docker-entrypoint.sh: exec format error |
# ! / b i n / s h \r \n |
Windows line endings | exec /usr/local/bin/docker-entrypoint.sh: no such file or directory |
The CRLF row is the one that misleads people. The kernel does honour the shebang, but it takes everything up to the newline as the interpreter path, so it looks for a program called /bin/sh\r. That file doesn’t exist, the kernel returns ENOENT, and you get “no such file or directory” for a script that is plainly there. It belongs in the same investigation even though the message differs.
Fix the source rather than the symptom: add a .gitattributes entry such as *.sh text eol=lf so Git checks scripts out with LF endings, save the file without a BOM, and make sure the first line is #!/bin/sh (or the interpreter you need). If you must repair a file during the build, RUN sed -i 's/\r$//' /usr/local/bin/docker-entrypoint.sh after the COPY strips the carriage returns.
Pinning the platform in Compose, CI and Kubernetes
- In
docker-compose.yml, addplatform: linux/amd64under the service while you migrate. - In CI, build on the same architecture you deploy to and pass
--platformexplicitly. - In Kubernetes, a node can run a foreign-architecture image only if it has
binfmt_miscemulation registered, which managed node images normally don’t. Without it, a single-platform image of the wrong architecture pulls fine and then the Pod entersCrashLoopBackOffwith this error in its logs. A multi-platform index that lacks the node’s platform fails earlier, at pull time.
Cheaper arm64 CI runners, amd64 production nodes
Picture a team that moves CI to arm64 runners to save money while its production nodes stay amd64. The next image builds as linux/arm64, since a build defaults to the builder’s architecture. Pods pull it without complaint and then restart with exec format error in their logs. Two commands settle it: docker image inspect on the built tag (or docker buildx imagetools inspect against the registry) shows linux/arm64, and kubectl get nodes -L kubernetes.io/arch shows amd64 on every node. The fix is to build --platform linux/amd64, or to push a multi-platform image with buildx --platform linux/amd64,linux/arm64 --push, and to add a pipeline step that fails when the pushed tag lacks the deploy platform.
Trying to reproduce it with docker run --platform linux/amd64 doesn’t work. If the tag has no amd64 variant, Docker refuses to pull or run it with a platform error instead of starting the container, so inspecting the manifest is the reliable check.
Why QEMU emulation is a bridge, not a fix
The reflex fix is to enable QEMU emulation on the host and move on. That works, but every instruction is translated: builds and test runs become several times slower, and the underlying portability bug (an arm64-only base or a baked-in native module) stays hidden until a real node of the other architecture hits it. Use emulation to test an image you can’t yet build natively, and build for the target architecture before anything ships.
Exercise: it builds everywhere and crashes only in the cluster
“An image builds and pushes without errors, runs on every developer’s machine, but the Kubernetes Pods it deploys to keep crashing with exec format error. Where do you look first, and how do you stop it recurring?”
The answer an interviewer wants
Two machines can agree on everything except CPU architecture, so I would compare the image’s platform with the node’s architecture before reading application code. docker image inspect <tag> --format '{{.Architecture}}' (or docker buildx imagetools inspect for the registry copy) gives the image side; kubectl get nodes -L kubernetes.io/arch gives the node side. A mismatch explains a faultless build that fails only at run time, and “runs on every developer’s machine” fits too, because Docker Desktop emulates the other architecture. If the architectures match, I’d read the first bytes of the entrypoint script for a missing shebang or a BOM. The lasting fix is to build for the deploy target: pass --platform in CI, or publish a multi-platform image so each node pulls the right variant, and assert the platform in the pipeline. Emulation on the nodes would only mask it and slow everything down.