🚨 Docker Error Guide: 'image does not match the specified platform' — Pull the Right Architecture

Overview

Docker raises this when you request a specific platform for an image whose local (or single-arch) manifest is for a different architecture. Unlike the non-fatal requested image's platform ... does not match the detected host platform warning, this one is a hard error that stops the run:

docker: Error response from daemon: image with reference myapp:latest was found but does not match the specified platform: wanted linux/amd64, actual: linux/arm64.

The daemon located the image by name but its architecture (linux/arm64) is not the one you asked for (linux/amd64), and there is no matching variant available to satisfy the request. Nothing runs.

Symptoms

• docker run --platform linux/amd64 myapp fails even though docker images lists myapp.
• The image was built on an Apple Silicon / ARM host and later used on an x86_64 host (or vice versa).
• A docker compose service with platform: linux/amd64 fails on an ARM developer laptop.
• docker pull succeeded but a subsequent --platform-qualified run rejects the cached image.
• The image is single-arch (no multi-platform manifest list), so the requested arch simply does not exist.

Common Root Causes

• Single-arch local image — the image was built for one architecture only, and you now request a different one with --platform.
• Explicit --platform mismatch — a docker run/build --platform or Compose platform: value that does not match the image you actually have.
• Mixed-architecture team — images built on Apple Silicon (arm64) consumed on amd64 CI/servers without a multi-arch build.
• Stale local cache — an older single-arch copy is cached locally, so Docker uses it instead of pulling a matching variant from the registry.
• Registry image lacks the arch — the upstream repository never published the requested platform in its manifest list.
• Emulation not installed — you intend to run a foreign arch via QEMU/binfmt, but the emulator is missing so the daemon refuses the mismatch.

Diagnostic Workflow

First, confirm your host architecture and what platform you are actually requesting:

docker version --format 'Server: {{.Server.Os}}/{{.Server.Arch}}'
uname -m

Inspect the architecture of the local image the daemon matched:

docker image inspect myapp:latest --format '{{.Os}}/{{.Architecture}}{{if .Variant}}/{{.Variant}}{{end}}'

Ask the registry which platforms the tag actually publishes (this reads the remote manifest list without pulling):

docker buildx imagetools inspect myapp:latest
docker manifest inspect myapp:latest | grep -A2 platform

If you expect QEMU emulation, verify binfmt handlers are registered:

docker run --rm --privileged tonistiigi/binfmt
ls /proc/sys/fs/binfmt_misc/ | grep -i qemu

Check whether a Compose file is forcing a platform:

services:
  web:
    image: myapp:latest
    platform: linux/amd64   # remove or match this to the available arch

Example Root Cause Analysis

A team built an internal service on Apple Silicon laptops and pushed a single-arch image. CI on an x86_64 runner then failed:

docker run --platform linux/amd64 registry.internal/myapp:1.4.0
# Error response from daemon: image with reference registry.internal/myapp:1.4.0
#   was found but does not match the specified platform: wanted linux/amd64,
#   actual: linux/arm64.

docker buildx imagetools inspect confirmed the tag only had an arm64 entry — there was no amd64 variant to satisfy the request. The real fix was to publish a multi-arch image so both CI and laptops resolve correctly:

docker buildx create --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.internal/myapp:1.4.0 \
  --push .

After the multi-arch push, imagetools inspect listed both platforms and the --platform linux/amd64 run resolved the correct variant automatically. For a one-off case where you only need to run the foreign arch locally, installing binfmt/QEMU and letting Docker emulate is the alternative:

docker run --rm --privileged tonistiigi/binfmt --install all
docker run --platform linux/amd64 registry.internal/myapp:1.4.0

Prevention Best Practices

• Build and publish multi-arch images with docker buildx build --platform linux/amd64,linux/arm64 --push so every consumer resolves the right variant.
• Verify a tag’s platforms with docker buildx imagetools inspect before depending on it in CI.
• Avoid hardcoding --platform / Compose platform: unless you truly need cross-arch emulation; let Docker pick the host-matching variant.
• Keep local caches fresh — docker pull (or --pull on build) so a stale single-arch copy is not reused.
• Install QEMU/binfmt on hosts that must run foreign architectures, and expect the performance cost of emulation.
• Standardize CI runner architecture, or run a matrix, so images are exercised on every target arch.

Quick Command Reference

# Host + requested platform
docker version --format '{{.Server.Os}}/{{.Server.Arch}}'

# Architecture of the local image
docker image inspect myapp:latest --format '{{.Os}}/{{.Architecture}}'

# What platforms does the tag publish?
docker buildx imagetools inspect myapp:latest

# Build and push a multi-arch image (the durable fix)
docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest --push .

# Enable emulation to run a foreign arch locally
docker run --rm --privileged tonistiigi/binfmt --install all

# Force a fresh pull of the matching variant
docker pull --platform linux/amd64 myapp:latest

Conclusion

This is a hard platform error, distinct from the cosmetic host-mismatch warning: Docker found the image but has no variant for the architecture you asked for. The right long-term fix is to publish a multi-arch image with buildx so amd64 and arm64 consumers each get the correct manifest. For one-off cross-arch runs, install QEMU/binfmt and let Docker emulate — accepting the speed penalty. Always confirm available platforms with imagetools inspect before wiring an image into CI.

For related architecture issues, see the no matching manifest for linux/amd64 guide, the exec format error guide, and more fixes in the Docker guides.