🚨 Docker Error Guide: 'no matching manifest for linux/amd64 in the manifest list entries' Platform Mismatch

Exact Error Message

When an image exists but not for your CPU architecture, the daemon returns:

no matching manifest for linux/amd64 in the manifest list entries

The architecture in the message reflects your host. On Apple Silicon or an ARM server you will instead see:

no matching manifest for linux/arm64/v8 in the manifest list entries

no matching manifest for linux/arm/v7 in the manifest list entries

You can read the repository and the tag exists — this is purely a platform-selection failure when resolving a multi-arch manifest list.

This error has become far more common as ARM hardware spread into the mainstream: Apple Silicon laptops, AWS Graviton, Ampere cloud instances, and Raspberry Pi all run arm64, while most production cloud fleets and CI runners remain amd64. An image built on one and run on the other will hit this the moment the architectures diverge.

What It Means

A multi-arch image is published as a manifest list (an OCI index): one tag pointing at several per-platform manifests, e.g. linux/amd64, linux/arm64. When you pull, the daemon picks the entry matching your host’s os/arch. no matching manifest for linux/amd64 in the manifest list entries means the daemon authorized the pull and found the manifest list, but none of its entries match your platform. The image simply was not published for your architecture — distinct from manifest unknown (the tag itself is missing) and from an auth error.

Common Causes

• Image published for other architectures only. An arm64-only image pulled on an amd64 host (or the reverse).
• Multi-arch image on an unsupported platform. The list covers amd64/arm64 but you are on arm/v7, ppc64le, or s390x.
• Built on Apple Silicon, deployed to amd64. A docker build on an M-series Mac produces an arm64 image; pushing it and deploying to an amd64 server fails on pull.
• Missing --platform. You want a specific platform but let the daemon default to the host’s, which the image lacks.
• buildx single-arch push. A buildx build --push without --platform (or with only one) publishes a single-arch image where consumers expect multi-arch.

How to Reproduce the Error

On an amd64 host, pull an image published only for arm64:

uname -m
docker pull --platform=linux/amd64 myorg/arm64-only:latest

x86_64
no matching manifest for linux/amd64 in the manifest list entries

Diagnostic Commands

Confirm your host architecture first:

uname -m
docker info --format '{{.Architecture}} {{.OSType}}'

x86_64
x86_64 linux

List exactly which platforms the image publishes. docker manifest inspect shows each entry’s platform block:

docker manifest inspect myorg/api:latest | grep -A3 platform

"platform": {
  "architecture": "arm64",
  "os": "linux"
}

docker buildx imagetools inspect gives the same picture in a friendlier table:

docker buildx imagetools inspect myorg/api:latest

Name:      docker.io/myorg/api:latest
MediaType: application/vnd.oci.image.index.v1+json
Manifests:
  Platform: linux/arm64

If only linux/arm64 appears and you are on x86_64, the image was never built for your platform — that is the whole problem.

Step-by-Step Resolution

You only need amd64 and the image lacks it: the image must be rebuilt for your platform. If you control the build, do a multi-arch build (below). If you do not, ask the publisher or find an amd64 variant.

You can run the other arch via emulation: install QEMU/binfmt and pull with an explicit --platform. This runs the foreign-arch image under emulation (slower, but works for many workloads):

docker run --privileged --rm tonistiigi/binfmt --install all
docker pull --platform=linux/arm64 myorg/api:latest
docker run --platform=linux/arm64 myorg/api:latest

You are the publisher — build and push multi-arch. Use buildx with a builder that supports multiple platforms, and push a manifest list:

docker buildx create --use --name multi
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myorg/api:latest --push .
docker buildx imagetools inspect myorg/api:latest

The final imagetools inspect should now list both linux/amd64 and linux/arm64.

You built on Apple Silicon and deploy to amd64. Either build with --platform=linux/amd64 (emulated on the Mac) or, better, do the multi-arch buildx build --push above so both architectures ship under one tag.

Quick one-off cross-build of a single platform:

docker buildx build --platform linux/amd64 -t myorg/api:amd64 --push .

A worked example. A developer on an M-series Mac builds and pushes myorg/api:latest, then the staging cluster (amd64) fails on deploy with no matching manifest for linux/amd64 in the manifest list entries. Inspecting the tag confirms it:

docker buildx imagetools inspect myorg/api:latest

Manifests:
  Platform: linux/arm64

Only arm64 is published, because docker build on the Mac defaulted to the host architecture. The fix is a multi-arch build that covers both targets:

docker buildx build --platform linux/amd64,linux/arm64 -t myorg/api:latest --push .

After the rebuild, imagetools inspect lists both platforms and the staging deploy resolves the linux/amd64 entry cleanly. The same fix prevents the reverse failure when an arm64 Graviton fleet later joins the deploy targets.

Note on emulation tradeoffs. Running an arm64 image on amd64 (or vice versa) under QEMU works but is significantly slower and occasionally trips on syscalls the emulator does not fully cover. Use it for short-lived tasks and CI cross-builds; for production throughput, ship a native manifest for the target platform instead of relying on emulation at runtime.

How to Prevent the Issue

• Standardize on multi-arch buildx build --push for any image consumed on more than one architecture.
• Verify published platforms in CI with docker buildx imagetools inspect and fail if a required platform is missing.
• Pin --platform explicitly in CI and Dockerfiles (FROM --platform=$TARGETPLATFORM) when reproducibility across hosts matters.
• Keep QEMU/binfmt installed on build hosts that cross-build, so emulated builds do not silently fall back to host-only.
• Document which architectures your deploy targets use (amd64 cloud vs arm64 Graviton/Apple Silicon) so builds cover them.

Related Docker Errors

• Docker Error Guide: ‘manifest unknown’ — the tag itself is missing, not just your platform’s entry.
• Docker Error Guide: ‘pull access denied’ — the registry will not let you read the repository at all.
• See more Docker troubleshooting guides.