A container starts and stops at once with exec format error
exec /usr/bin/sh: exec format errorShort answer
The kernel was asked to run a file it cannot execute. In Docker this is almost always an image built for another CPU architecture, such as arm64 on an amd64 runner. Compare the image platform with uname -m, then build for the right platform. A script with no shebang line causes the same message.
Fix it fast
1Find out which cause you have
Compare the CPU of the machine that runs the container with the platforms the image was published for.
uname -m docker buildx imagetools inspect IMAGE:TAG2Match what you see, then jump to its fix
- 1
uname -m prints x86_64 but the image only lists linux/arm64, or the other way round (typical: image built on an Apple silicon laptop, run on an amd64 CI runner or server)The image was built for a different architecture than the hostFix - 2
You build for a platform other than the host's, and RUN steps fail with exec format error while buildingEmulation is not set up on a Docker Engine hostFix - 3
The image platform matches the host, but the error names your own script or binaryThe entrypoint is a script with no shebang, or a binary for another OSFix - 4
Builds for the other architecture are very slow or crash with this error in the compiler stageA build stage runs under emulation when it could run nativelyFix
- 1
What does the error look like?
exec /usr/bin/sh: exec format error
Cause 1 of 4
The image was built for a different architecture than the host
1Check
In the imagetools output, look at the Platform lines under Manifests. If the host's platform is not there, the host cannot run the image without emulation.
docker buildx imagetools inspect IMAGE:TAG | grep Platform2Fix
Build for the platform that will run it, or for several at once, and push that tag.
docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.com/app:1.0 --push .3Verify
The tag now lists both platforms, and the container starts on the amd64 host.
docker buildx imagetools inspect registry.example.com/app:1.0Confirmed by docs.docker.com
Cause 2 of 4
Emulation is not set up on a Docker Engine host
1Check
Docker Desktop includes QEMU. On plain Docker Engine, the emulators must be registered with the kernel; look for the F flag in the qemu entries.
cat /proc/sys/fs/binfmt_misc/qemu-*2Fix
Register the emulators once on the host that builds, then repeat the build.
docker run --privileged --rm tonistiigi/binfmt --install all3Verify
The qemu entries now exist and the multi-platform build gets past its RUN steps.
cat /proc/sys/fs/binfmt_misc/qemu-*
docker buildx build --platform linux/arm64 .Confirmed by docs.docker.com
Cause 3 of 4
The entrypoint is a script with no shebang, or a binary for another OS
1Check
Linux reports ENOEXEC when a file is not in a recognised format or is for the wrong architecture. An interpreter script is recognised by a first line like #!/bin/sh.
head -n 1 docker-entrypoint.sh2Fix
Add the interpreter line to the first line of the script, and make sure the file is a Linux executable, not a macOS or Windows build output.
#!/bin/sh
set -e
exec "$@"3Verify
Rebuild the image and start the container.
docker build -t app . && docker run --rm appConfirmed by man7.org
Cause 4 of 4
A build stage runs under emulation when it could run natively
1Check
Look for a build stage that has no platform pinned. By default the stage uses the target platform of the build.
grep -n '^FROM' Dockerfile2Fix
Pin the build stage to the builder's own platform and cross-compile, passing the target arguments to your compiler.
FROM --platform=$BUILDPLATFORM golang:alpine AS build
ARG TARGETOS
ARG TARGETARCH
RUN GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /server .3Verify
The multi-platform build finishes without running the compiler under emulation.
docker buildx build --platform linux/amd64,linux/arm64 .Confirmed by docs.docker.com
How do I stop it coming back?
- Publish multi-platform tags from CI instead of pushing from a laptop.
- Check imagetools output before deploying a new tag.
- Start every script with a shebang line.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
A binary built in one image will not start in another because of glibc
/lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by ./app)
The binary was linked against a newer glibc than the image it now runs in.
3 causes, each with a fixServers
Apache logs SIGWINCH and exits on its own
the httpd container stops although nothing crashed
SIGWINCH is Apache's graceful-stop signal.
2 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
dnf fails to download repo metadata in a CentOS 8 Docker build
The same Dockerfile built fine before 2022
CentOS Linux 8 reached end of life on 31 December 2021 and its content left the mirrors.
2 causes, each with a fixServers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fix