Docker 'exec format error'? Your image is the wrong CPU type
Short answer: "exec format error" when a container starts usually means the image was built for a different CPU architecture than the machine running it. A common case is an image built on an ARM-based laptop (linux/arm64) being deployed to an Intel or AMD server (linux/amd64), or the other way round. Containers share the host's kernel, so the program inside has to match the host's processor unless emulation is in place. Fix it by building for the server's platform explicitly, or by publishing a multi-platform image that contains both.
Why the error happens
Docker's documentation explains the root of the problem: containers share the host kernel, so code inside a container must be compatible with the host's architecture. That's why you can't run a linux/amd64 container on an arm64 host without emulation.
When you run docker build with no extra options, Docker builds for the machine you're on. Many developer laptops are now ARM-based, while plenty of cloud servers, shared hosting platforms and CI runners still use x86-64. Push the laptop-built image, pull it on the server, and the first binary the container tries to run is in a format the server's CPU can't execute. The kernel refuses it, and you see "exec format error", often with the container exiting immediately and restarting in a loop.
Confirm it's an architecture mismatch
Before changing your build, check both sides:
- On the server, find the host architecture (for example with
uname -m;x86_64means amd64,aarch64means arm64). - Inspect the image to see which architecture it was built for.
docker image inspectshows an architecture field for single-platform images. - Look at Docker's warnings when you pull or run. A message that the image's platform doesn't match the host's is a strong clue.
If both match and you still see the error, the problem may be elsewhere, such as a shell script saved with Windows line endings or a missing interpreter line at the top of an entrypoint script.
Fix 1: build for the server's platform
The quickest fix is to tell Docker which platform you want:
docker buildx build --platform linux/amd64 -t registry.example.com/shop-api:1.4 --push .
On an ARM laptop this produces an x86-64 image, normally using emulation. Docker's documentation notes that building under emulation with QEMU needs no changes to your Dockerfile, and that Docker Desktop supports it by default with its bundled QEMU. The trade-off is speed: Docker warns emulation can be much slower than native builds, especially for compiling and compressing.
You can also set --platform when running a container, which is useful for testing whether an image works under emulation, but it doesn't fix an image that only exists for the wrong architecture.
Fix 2: publish a multi-platform image
If your team uses a mix of ARM laptops and x86 servers, publish one image that works on both. Docker describes multi-platform images as having a manifest list pointing to separate manifests for each platform. When a machine pulls the image, it receives the variant for its own architecture.
docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.com/shop-api:1.4 --push .
This needs an image store that supports manifest lists. According to Docker's docs, Docker Desktop and recent Docker Engine versions use the containerd image store by default, which supports this without extra setup. On older engines you can enable the containerd store or create a builder using the docker-container driver.
Fix 3: build in CI on the right machine
For production images, it's often simplest to build in your CI pipeline on a runner with the same architecture as your servers. That avoids emulation entirely and means the image deployed is the one your pipeline tested. Docker also describes using multiple native build nodes, one per architecture, for faster multi-platform builds.
Make your Dockerfile platform-aware
A few habits avoid surprises:
- Use base images that publish multiple platforms. Most official images do, but some smaller or older images exist for one architecture only.
- Don't download architecture-specific binaries with a fixed URL. A Dockerfile that downloads an amd64 binary will break on arm64 builds, and vice versa.
- Use the build arguments Docker provides.
BUILDPLATFORMandTARGETPLATFORMare available automatically. Docker's example pins the build stage to the builder's native platform with--platform=$BUILDPLATFORMand then cross-compiles for$TARGETPLATFORM, which is much faster than emulating the whole build. - Check compiled language dependencies. Packages with native extensions need building or downloading for each platform.
Check the rest of the deployment
If you deploy with Docker Compose or a hosting platform, confirm nothing forces the wrong platform, such as a platform: setting left in a compose file from local testing. Tag images clearly and avoid reusing the same tag for single-platform and multi-platform builds, so a later pull doesn't fetch an unexpected variant.
An illustrative example
A web agency in Manchester builds a client's booking API on new ARM laptops and pushes the image to its registry. The x86 server pulls the update, and the API container restarts over and over with "exec format error". The developer confirms the image is arm64 and the server x86_64. They move image builds into CI on an x86 runner, add a multi-platform build for the image developers pull locally, and replace a hard-coded amd64 binary download in the Dockerfile with one chosen from TARGETPLATFORM.
FAQ
Can I just run the ARM image on the x86 server with emulation?
It's possible with emulation installed, but slower and less predictable. Build the correct image for production.
Why did it work on my colleague's machine?
Their machine likely has the same architecture as the image, or Docker Desktop's emulation handled it transparently.
Does this affect Windows containers?
Docker's documentation notes you also can't run Windows containers on a Linux host. That's an operating system mismatch rather than a CPU one.
Do I need separate tags per architecture?
Not with a multi-platform image. One tag covers both, and each machine pulls its own variant.
If containers keep failing on your servers after building on a laptop and you want a build setup that works everywhere, tell us how you build and deploy today.