highIntermediateSymptom-first#images#architecture#arm64#amd64#multiarch

Exec format error — image built for wrong CPU architecture

exec format error when starting container on ARM host pulling amd64 image

Likely source:configurationavailability

Focused incident mode — strips away everything but this runbook.

Symptoms

  • exec format error when starting container on ARM host pulling amd64 image
  • docker run fails immediately with 'exec user process caused: exec format error'
  • Image works on Intel but fails on Apple Silicon or ARM servers

Docker Desktop on Apple Silicon includes QEMU emulation by default. On bare-metal ARM Linux servers, you must install qemu-user-static manually.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Image platform metadata

    docker manifest inspect <IMAGE>:<TAG> | grep architecture

  • Host architecture

    uname -m

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • docker inspect shows Architecture: amd64 on an aarch64 host
  • exit code 1 (exec format error) immediately on start

Confirm before fixing

docker inspect <IMAGE> --format='Architecture={{.Architecture}}'
READ

Confirm the image architecture

Fix

docker buildx build --platform linux/amd64,linux/arm64 -t <IMAGE> --push .
CHANGE

Build a multi-arch image with buildx

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
uname -m
READ

Identify host architecture

2
docker inspect <IMAGE> --format='Architecture={{.Architecture}}'
READ

Identify image architecture

3
docker buildx build --platform linux/amd64,linux/arm64 -t <IMAGE> --push .
CHANGE

Build a multi-arch image (preferred fix)

4
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
DESTRUCTIVE

Install QEMU emulation as a workaround

Prevention

  • Build multi-arch images with docker buildx build --platform linux/amd64,linux/arm64.
  • Use CI pipelines that test on both amd64 and arm64 runners.
  • Pin base images to multi-arch tags (e.g., node:20-slim, not node:20-slim-amd64).
  • Add platform checks to deployment scripts: docker inspect --format='{{.Architecture}}'.

Related runbooks

Same stack, same failure family — worth a skim.

ImagePullBackOff / ErrImagePull — pod can't fetch its imagehigh

Pod stuck in ImagePullBackOff or ErrImagePull

KubernetesFoundation3 causes
Open runbook
Docker Hub rate limit — anonymous or free-tier pull limit exceededhigh

docker pull returns 'You have reached your pull rate limit'

DockerFoundation3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.