Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Docker: exec user process caused: exec format error

An arm64 image on an amd64 host is a runtime failure, not a pull failure. Diagnose the platform, build for the target, publish multi-arch, and spot the script variant.

~5 min readDocker
#Docker#Buildx#Deployment#Debugging
3D diagram of a container whose binary connector does not fit the host socket grid, headline EXEC FORMAT

Introduction & Quick Summary

Symptom. A container that runs perfectly on a laptop dies instantly elsewhere:

standard_init_linux.go:228: exec user process caused: exec format error

In Kubernetes the same failure arrives as a restart loop:

code
$ kubectl logs pod/api-7c9f8b6d5-x2lqk exec /usr/local/bin/api: exec format error

Cause. The image's architecture does not match the machine's. The most common route is a build on an Apple Silicon Mac (arm64) that produced an arm64 image, pushed unchanged to an amd64 server or to CI. The second most common is a binary compiled for the wrong target inside a multi-stage build. exec format error is ENOEXEC: the kernel read the ELF header, found a machine type it cannot run, and refused before any of your code started.

Fix. Build for the platform you deploy to (docker build --platform linux/amd64, or publish a multi-arch image with buildx), and make sure cross-compiled binaries get TARGETARCH rather than the build host's GOARCH. Running an arm64 image on an amd64 host through emulation works locally and is not a fix for production.

Core Mechanics, Signatures & Reproducible Setup

An image manifest names a platform. docker pull resolves the tag to the manifest matching the local architecture, but a tag that was built for one architecture only has a single manifest, so every host gets the same bytes.

Diagnose in three commands, before changing anything:

bash
uname -m # host: x86_64 or aarch64 docker image inspect api:latest --format \ '{{.Os}}/{{.Architecture}}{{if .Variant}}/{{.Variant}}{{end}}' # e.g. linux/arm64 docker buildx imagetools inspect registry.example.com/api:latest # Name: .../api:latest # MediaType: application/vnd.oci.image.index.v1+json # Manifests: # Platform: linux/amd64 # Platform: linux/arm64

The third command is the one that tells the truth about a registry tag: no Manifests: list means a single-arch image, and the platform line under it names the only architecture that can run it.

Reproduce and fix on an Apple Silicon machine targeting an amd64 server:

# Reproduce: default build on arm64 docker build -t api:bad . && docker push registry.example.com/api:bad # On the amd64 host docker run --rm registry.example.com/api:bad # standard_init_linux.go:228: exec user process caused: exec format error # Fix: build (or rebuild and push) for the target platform docker build --platform linux/amd64 -t api:good . docker run --rm api:good

--platform on docker run is local emulation only; it does not change what was pushed.

Key Comparison Table

The three startup messages look similar and have different causes:

MessageMeaningTypical cause
exec format errorELF header machine type unreadable by this kernelarm64 image on amd64, 32-bit binary on 64-bit host, text file with no shebang
no such file or directoryThe interpreter named in the shebang is missing#!/bin/bash in an Alpine (musl, no bash) image, or CRLF line endings
permission deniedFile exists but is not executableCopy lost the exec bit, or a read-only filesystem

Ways to ship one image to several architectures:

ApproachCommand shapeResultCost
Single-arch for the targetdocker build --platform linux/amd64One manifest, correct for deployFast, no emulation
Multi-arch with buildxdocker buildx build --platform linux/amd64,linux/arm64 --pushIndex with both manifestsSlower; needs a builder and QEMU
Per-arch jobs in CIOne runner per architecture, then docker manifest createIndex assembled from two pushesMost control, most YAML
Compose with a platformplatform: linux/amd64 in servicesLocal pull of the right variantOnly affects local runs

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. Make the local build match production

For a team on mixed laptops, set the default platform once so nobody produces a laptop-only image:

bash
export DOCKER_DEFAULT_PLATFORM=linux/amd64 # shell profile or .envrc

In Compose, be explicit for both build and run:

services: api: build: context: . platforms: ["linux/amd64"] platform: linux/amd64 image: registry.example.com/api:dev

build.platforms with a single entry is fine for docker compose build; the plural form with several platforms requires buildx and a push.

2. Publish a real multi-arch image

A multi-arch tag is one registry object pointing at several manifests. Buildx writes it with --push:

bash
docker buildx create --name multi --driver docker-container --bootstrap --use docker buildx build \ --platform linux/amd64,linux/arm64 \ --tag registry.example.com/api:1.4.0 \ --push . docker buildx imagetools inspect registry.example.com/api:1.4.0

Two mistakes account for most failures here. --load only accepts a single platform, so --platform ... --load fails or silently keeps one architecture. And without --push, the build succeeds and the tag in the registry is untouched, which looks exactly like the original bug on the next deploy.

3. Cross-compiling inside a multi-stage build

A Go or Rust build stage runs on the build host's architecture unless told otherwise, so GOARCH defaults to the builder's and produces the wrong binary even when the final image is amd64:

dockerfile
# syntax=docker/dockerfile:1 FROM --platform=$BUILDPLATFORM golang:1.24 AS build ARG TARGETOS TARGETARCH WORKDIR /src COPY . . RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \ go build -trimpath -ldflags="-s -w" -o /out/api ./cmd/api FROM gcr.io/distroless/static-debian12:nonroot COPY --from=build /out/api /usr/local/bin/api ENTRYPOINT ["/usr/local/bin/api"]

$BUILDPLATFORM keeps the compiler native (fast), and $TARGETARCH produces the binary the final image needs. Using FROM --platform=$TARGETPLATFORM for the build stage forces emulation: correct output, several times slower.

4. Kubernetes: the pod that restarts instead of failing to pull

An architecture mismatch is a runtime failure, so the image pulls successfully and the container exits immediately. That gives CrashLoopBackOff, not ImagePullBackOff, and the useful detail is in the events and the previous log:

bash
kubectl get nodes -o wide # check the ARCH column kubectl get pod api-7c9f8b6d5-x2lqk -o jsonpath='{.spec.nodeName}{"\n"}' kubectl describe pod api-7c9f8b6d5-x2lqk | tail -20 kubectl logs api-7c9f8b6d5-x2lqk --previous # exec /usr/local/bin/api: exec format error

With a mixed-architecture node pool, pin the workloads that only have one architecture:

spec: template: spec: nodeSelector: kubernetes.io/arch: amd64

The better fix is a multi-arch image; the node selector is the stopgap that prevents a scheduler from placing the pod on the arm64 node that cannot run it.

5. When the "binary" is a script

exec format error also appears for a file that is not an executable at all: a shell script without a shebang, executed through ENTRYPOINT ["./start.sh"], or a Windows-authored file with CRLF endings. The kernel sees no ELF header and no #! and returns ENOEXEC.

dockerfile
# Wrong: relies on the kernel to interpret a text file ENTRYPOINT ["./docker/start.sh"] # Right: name the interpreter ENTRYPOINT ["/bin/sh", "./docker/start.sh"] # Also right: make the script a real executable with a proper shebang # #!/bin/sh (first line, LF only) RUN chmod +x ./docker/start.sh

CRLF is the trap in the second variant: it produces no such file or directory for /bin/sh^M rather than exec format error, and both disappear after dos2unix.

6. Checking an image without running it

Before pushing, verify the artifact instead of waiting for a deploy to fail:

bash
docker create --name probe api:good >/dev/null docker export probe | tar -xO usr/local/bin/api > /tmp/api.bin docker rm probe >/dev/null file /tmp/api.bin # /tmp/api.bin: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked

file prints the machine type, which is the ground truth for an exec format error in a multi-stage build. On macOS, docker run --rm --platform linux/amd64 api:good arch answers the same in one line.

Common Compilation/Runtime Mistakes & Version Gotchas

  • --platform on docker run as the fix. It emulates locally and hides the problem; the pushed image is still the wrong architecture.
  • docker buildx build --load with two platforms. Only one is kept and the failure looks intermittent, depending on which host pulls it.
  • Assuming docker pull picks the right variant. It does only when the tag is a manifest list; a single-arch tag is served to everyone.
  • GOARCH inherited from the builder. Without ARG TARGETARCH the binary matches the CI runner, not the deploy target; this is invisible until the first amd64 deploy from an arm64 runner.
  • Distroless and scratch images with no shell. docker exec cannot help you inspect anything; copy the binary out with docker export as above, or add a debug stage.
  • Base image platform pinning. FROM --platform=linux/amd64 in a Dockerfile pins that stage but not the final image, so mixing pinned and unpinned stages can produce a working build with a mismatched runtime layer.- docker-compose platform: versus build.platforms. The first selects a variant at run time, the second decides what is built; a compose file with only the first can build arm64 and run amd64 through emulation, which is slow and easy to mistake for correct.
  • Alpine on a glibc host, and the reverse. A musl binary in a Debian image is a different error (not found for the loader), but it arrives in the same investigation and is fixed the same way: check what the binary was linked against with file and ldd before choosing a base image.

Related tools. Format a Compose file with the docker-compose reference when a platform key sits at the wrong level — it is valid under services.<name> and under build, and a misplacement is silently ignored — and confirm the copied entrypoint kept its executable bit with the chmod calculator when the message is permission denied rather than exec format error.

Official references

primary documentation

The Docker documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.