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.

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:
$ kubectl logs pod/api-7c9f8b6d5-x2lqk
exec /usr/local/bin/api: exec format errorCause. 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:
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/arm64The 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:
| Message | Meaning | Typical cause |
|---|---|---|
exec format error | ELF header machine type unreadable by this kernel | arm64 image on amd64, 32-bit binary on 64-bit host, text file with no shebang |
no such file or directory | The interpreter named in the shebang is missing | #!/bin/bash in an Alpine (musl, no bash) image, or CRLF line endings |
permission denied | File exists but is not executable | Copy lost the exec bit, or a read-only filesystem |
Ways to ship one image to several architectures:
| Approach | Command shape | Result | Cost |
|---|---|---|---|
| Single-arch for the target | docker build --platform linux/amd64 | One manifest, correct for deploy | Fast, no emulation |
| Multi-arch with buildx | docker buildx build --platform linux/amd64,linux/arm64 --push | Index with both manifests | Slower; needs a builder and QEMU |
| Per-arch jobs in CI | One runner per architecture, then docker manifest create | Index assembled from two pushes | Most control, most YAML |
| Compose with a platform | platform: linux/amd64 in services | Local pull of the right variant | Only 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:
export DOCKER_DEFAULT_PLATFORM=linux/amd64 # shell profile or .envrcIn Compose, be explicit for both build and run:
services:
api:
build:
context: .
platforms: ["linux/amd64"]
platform: linux/amd64
image: registry.example.com/api:devbuild.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:
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.0Two 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:
# syntax=docker/dockerfile:1
FROM 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 /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:
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 errorWith a mixed-architecture node pool, pin the workloads that only have one architecture:
spec:
template:
spec:
nodeSelector:
kubernetes.io/arch: amd64The 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.
# 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.shCRLF 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:
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 linkedfile 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
--platformondocker runas the fix. It emulates locally and hides the problem; the pushed image is still the wrong architecture.docker buildx build --loadwith two platforms. Only one is kept and the failure looks intermittent, depending on which host pulls it.- Assuming
docker pullpicks the right variant. It does only when the tag is a manifest list; a single-arch tag is served to everyone. GOARCHinherited from the builder. WithoutARG TARGETARCHthe 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 execcannot help you inspect anything; copy the binary out withdocker exportas above, or add a debug stage. - Base image platform pinning.
FROM --platform=linux/amd64in 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-composeplatform:versusbuild.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 foundfor the loader), but it arrives in the same investigation and is fixed the same way: check what the binary was linked against withfileandlddbefore 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 documentationThe Docker documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Docker guides
All Docker guidesDocker Compose: bind: address already in use and Port Conflicts
A published port is a host socket, and two projects cannot own it. How to find the real owner, why an override file merged instead of replacing, and how to publish dynamically.
Alpine musl vs Debian slim: DNS Timeouts and Native Builds
musl rejects manylinux wheels and linux-x64-gnu prebuilds, so the installer starts compiling without a toolchain. And ndots:5 in Kubernetes adds five seconds per lookup.
Docker Compose Connection Refused: localhost vs Service DNS
localhost inside a container is that container. Compose resolves service names on a shared network, depends_on does not wait for readiness, and binding loopback breaks the rest.
Docker BuildKit failed to solve: Exit Codes, Build Context, and Network
BuildKit puts every failure under one prefix. The exit code after did not complete successfully is the whole diagnosis: 100 is apt, 127 is a missing binary, and cache key is a file outside the context.
More in Docker
All Docker guidesThe guides filed next to this one in Docker, in library order.