Docker Tip #101: Fix Exec Format Error Due to CPU Architecture Mismatch
You may get this error if you try to run a Docker image that was built with a different CPU architecture, such as amd64 vs arm64.
Prefer video? Here’s a recorded version of this tip on YouTube which covers this topic.
When running a container you may see exec format error which is thrown by
whatever process your container is trying to start. This could be a shell, web
server or whatever it happens to be.
The most likely culprit here is you have an image that was built with a different CPU architecture than your machine. For example there’s only an amd64 image available but you have an arm64 CPU such as an Mx Mac or vice versa.
In the past I’ve also seen this error happen when an entrypoint script was saved with Windows line endings instead of Unix but we’re going to focus on a CPU architecture mismatch in this post.
You can check by running:
$ docker image inspect $YOUR_IMAGE_NAME | grep Architecture
"Architecture": "amd64",
If you see the wrong architecture type than your machine that’s your issue.
You can test this at run-time by setting a custom DOCKER_DEFAULT_PLATFORM:
$ DOCKER_DEFAULT_PLATFORM="linux/amd64" docker container run --rm -it debian:bookworm-slim
$ DOCKER_DEFAULT_PLATFORM="linux/arm64" docker container run --rm -it debian:bookworm-slim
Depending on your CPU architecture, one of the above commands will put you into
a Bash prompt while the other will throw an exec /usr/bin/bash: exec format error error.
An image can be built to support multiple architectures and the Docker client will pull the correct one but that only works if your architecture is available by whoever built the image.
You can build an image with a specific architure on demand with
DOCKER_DEFAULT_PLATFORM="linux/amd64" docker image build .... I’ve done this
on occasion for one off testing, such as building an amd64 image on an M2 Air
(work laptop) so it runs correctly on amd64 hardware in a pre-prod environment.
For a more permanent solution or public images it’s a good idea to build images for multiple architectures so more folks can use it. Here’s how to automate that with GitHub actions.