Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A container starts and stops at once with exec format error

Errorexec /usr/bin/sh: exec format error

Short 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.

  • Applies to Docker Engine 28, Docker Buildx 0.2x, GitLab Runner 17, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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:TAG
  2. 2Match what you see, then jump to its fix

    1. 1uname -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. 2You 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. 3The 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. 4Builds 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

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 Platform

2Fix

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.0

Confirmed by docs.docker.com

Did this fix it?

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 all

3Verify

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

Did this fix it?

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.sh

2Fix

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 app

Confirmed by man7.org

Did this fix it?

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' Dockerfile

2Fix

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

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.