"exec format error" — Apple Silicon and Multi-Architecture Docker Images

exec /usr/local/bin/node: exec format error

Or the slightly different message:

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) ...

Both mean the same thing: the container's binary is compiled for a CPU architecture your Docker host can't natively run. The common cases in 2026: you're on Apple Silicon (arm64) and pulled an amd64-only image, or you're on Intel and pulled an arm64-only image. The fix is to use an image that ships both architectures, force emulation, or specify the platform explicitly.

What architecture are you on?

docker version --format '{{.Server.Os}}/{{.Server.Arch}}'
# linux/arm64  (Apple Silicon Macs)
# linux/amd64  (Intel/AMD)

That's the platform Docker will pull by default for docker pull image.

Does the image have your architecture?

docker manifest inspect IMAGE_NAME | grep architecture

For an image like nginx:alpine:

"architecture": "amd64",
"architecture": "arm64",
"architecture": "arm",
"architecture": "386",
"architecture": "ppc64le",
"architecture": "s390x",

Many platforms — nginx ships builds for all of them. For a less popular image you might see only amd64. That's when the trouble starts on Apple Silicon.

Fix 1: force the platform Docker pulls

docker pull --platform linux/amd64 IMAGE_NAME
docker run --platform linux/amd64 IMAGE_NAME

On Apple Silicon, that explicitly pulls and runs the amd64 build. The container then runs under emulation (slow, but functional). The most common scenario is older or niche vendor images that haven't been rebuilt for arm64; this flag is the workaround.

You can also set the default for all your Docker commands:

export DOCKER_DEFAULT_PLATFORM=linux/amd64

I usually don't. Setting per-command is more predictable.

In Compose:

services:
  legacy-service:
    image: vendor/old-thing
    platform: linux/amd64

Fix 2: enable Rosetta for amd64 emulation on Apple Silicon

Docker Desktop 4.25+ on Apple Silicon uses Apple's Rosetta translation layer for amd64 emulation, which is dramatically faster than the default QEMU. Enable it:

Docker Desktop → Settings → General → "Use Rosetta for x86_64/amd64 emulation on Apple Silicon."

The speedup is significant. Things that took 10 minutes under QEMU might take 1-2 minutes with Rosetta. Doesn't help with arm64-only images on Intel — Rosetta is Apple-side only.

Fix 3: build (or find) an arm64 image

If you maintain the image, build it for arm64 too:

docker buildx build --platform linux/amd64,linux/arm64 -t my-image --push .

buildx (BuildKit's multi-platform builder) creates a manifest list — one tag pointing to multiple per-architecture images. Pulling on Apple Silicon gets arm64; pulling on Intel gets amd64. See docker buildx: Multi-Architecture Builds.

If you don't maintain the image, check if a community-maintained arm64 build exists elsewhere on Docker Hub or GHCR.

How emulation actually works

Docker Desktop on Mac uses Apple's hypervisor with a Linux VM. The VM is arm64 natively. When you run an amd64 image, the kernel hands the binary to QEMU (or Rosetta, if enabled) for instruction-by-instruction translation. The container then runs translated amd64 code on an arm64 CPU.

That's slower than native:

• QEMU emulation: 5-10x slower than native, sometimes more for CPU-heavy workloads.
• Rosetta emulation: 2-3x slower than native, much better than QEMU.

For "I just need to run this image occasionally," emulation is fine. For active development, native arm64 is significantly better.

Common scenarios

Older Postgres / MongoDB / Java images. Most have arm64 builds now, but old pinned versions might not. Either bump the version (preferred) or run with --platform linux/amd64.

Vendor-specific images (database drivers, CLI tools for specific cloud platforms). Some still ship amd64-only. --platform linux/amd64 is the workaround.

Building an image on Mac, deploying on Linux server. If your local build was on Apple Silicon (arm64) and you push to a Linux x86 server, the server can't run it. Either build multi-arch with buildx, or build with --platform linux/amd64 for the target.

M1/M2/M3/M4 fresh laptop, hitting issues on a project that worked on the old Intel MacBook. Almost always image arm64 availability. Run docker manifest inspect on the images in your Compose stack to see which ones don't have arm64; either find replacements or pin platform: linux/amd64 for those services.

Spot-check arm64 availability in a Compose stack

for img in $(docker compose config --images); do
  echo -n "$img: "
  docker manifest inspect "$img" 2>/dev/null | \
    grep -c '"architecture": "arm64"' || echo 0
done

That iterates over images in your docker-compose.yml and reports whether each has an arm64 manifest. Zero means no arm64 build.

Common pitfalls

• Image works on your machine but fails on your colleague's. Different CPU architectures and one of you got the wrong image. Pin platform explicitly or use a multi-arch image.
• Emulation works but tests are super slow. That's emulation. Don't conclude your app is slow; check what platform the container is running on.
• Rosetta enabled but only some images use it. Rosetta kicks in for amd64 binaries running on Apple Silicon. arm64 images run natively (no Rosetta). Both is fine.
• Building an image and pushing to a registry, then noticing it's the wrong arch on the server. Build with --platform linux/amd64 or with buildx for both architectures.

What to do next

• docker buildx: Multi-Architecture Builds — building one image for both arm64 and amd64.
• How to Install Docker — Apple Silicon specifics for Docker Desktop.
• Docker Cheat Sheet — including manifest inspect for checking image platforms.

FAQ