Fix “no matching manifest for linux/amd64 (or arm64)” in Docker

What this error means

The error “no matching manifest for linux/amd64 (or arm64) in the manifest list entries” appears when your Docker daemon requests an image for your host platform, but the image registry does not have a compatible architecture in its manifest list (multi-arch index). In short: you are pulling or building for an architecture the image/tag does not provide.

Typical causes:

• Pulling an image tag that only supports another architecture
• Using a base image in Dockerfile that lacks your target architecture
• Building on Apple Silicon (arm64) but using amd64-only images, or vice versa
• Old single-arch image tags; multi-arch variants may exist under different tags

Quickstart: diagnose and fix fast

1. Identify your host platform

docker info --format '{{.OSType}}/{{.Architecture}}'
# e.g. linux/arm64 on Apple Silicon; linux/amd64 on most PCs

1. Inspect the image’s manifest list

# Requires the tag to exist in a registry
docker manifest inspect IMAGE:TAG | jq '.manifests[].platform' 2>/dev/null || true

• If your platform is missing, choose a tag that includes it or rebuild the image as multi-arch.

1. Try forcing a platform (temporary workaround)

# Pull or run a specific architecture (uses emulation if needed)
docker pull --platform=linux/amd64 IMAGE:TAG
# or
docker run --rm --platform=linux/arm64 IMAGE:TAG uname -m

1. If you own the image: build and publish a multi-arch tag with Buildx

# One-time setup (Docker Desktop already has buildx)
docker buildx create --name xbuilder --use || docker buildx use xbuilder

# Build and push multi-arch
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t REGISTRY/REPO/IMAGE:TAG \
  --push .

# Verify
docker buildx imagetools inspect REGISTRY/REPO/IMAGE:TAG

Minimal working example: multi-arch build with Buildx (Go)

This example builds a tiny Go program into a multi-arch image that runs on both amd64 and arm64.

main.go

package main
import (
    "fmt"
    "runtime"
)
func main() {
    fmt.Printf("hello from %s/%s\n", runtime.GOOS, runtime.GOARCH)
}

Dockerfile

# Build stage uses the build platform to cross-compile
FROM --platform=$BUILDPLATFORM golang:1.22-alpine AS build
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY main.go .
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -trimpath -ldflags="-s -w" -o /out/app main.go

# Runtime stage must be multi-arch capable
FROM alpine:3.20
COPY --from=build /out/app /usr/local/bin/app
ENTRYPOINT ["/usr/local/bin/app"]

Build and test

# Create and use a builder (once per machine)
docker buildx create --name xbuilder --use || docker buildx use xbuilder

# Optional: enable binfmt for cross-building (non-Desktop Linux)
# docker run --privileged --rm tonistiigi/binfmt --install all

# Build and push a multi-arch image
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t YOURREG/hello-multiarch:0.1.0 \
  --push .

# Inspect supported platforms
docker buildx imagetools inspect YOURREG/hello-multiarch:0.1.0

# Run on your host (auto-selects matching arch)
docker run --rm YOURREG/hello-multiarch:0.1.0

# Force another arch (uses emulation if available)
docker run --rm --platform=linux/amd64 YOURREG/hello-multiarch:0.1.0

Common fixes by scenario

• Pulling third‑party images

  • Find a tag that includes your platform: use docker manifest inspect IMAGE:TAG.
  • If only one arch exists, consider --platform plus emulation. Expect slower performance.

• Dockerfile base image mismatch

  • Replace base images with multi-arch variants (e.g., alpine, debian, ubuntu, busybox).
  • Pin to a tag that is known multi-arch (e.g., alpine:3.20). Verify with docker manifest inspect.

• Compose services (docker compose)

  • Force a platform per service:

services:
  api:
    image: myorg/api:1.2.3
    platform: linux/arm64

• CI builds (GitHub Actions, GitLab CI, etc.)

  • Use Buildx with --platform linux/amd64,linux/arm64 and push to a registry.
  • Ensure QEMU/binfmt is installed on Linux runners if cross-building.

• Publishing multi-arch for existing single-arch images

  • If you already have :tag-amd64 and :tag-arm64 pushed, create a manifest list:

docker buildx imagetools create \
  -t REGISTRY/REPO/IMAGE:tag \
  REGISTRY/REPO/IMAGE:tag-amd64 \
  REGISTRY/REPO/IMAGE:tag-arm64

# Verify
docker buildx imagetools inspect REGISTRY/REPO/IMAGE:tag

Quick reference: symptoms and fixes

• Error when pulling: image tag lacks your architecture → choose a different tag or force --platform.
• Build fails at FROM: base image missing your arch → pick a multi-arch base tag.
• Works on amd64, fails on arm64: image is amd64-only → rebuild with Buildx multi-arch.

Pitfalls to avoid

• Using non-multi-arch base images: always check with docker manifest inspect.
• Forgetting target variables in multi-arch builds: use ARG TARGETOS TARGETARCH and build with Buildx.
• Assuming local docker load stores multi-arch: --load exports a single arch; use --push to publish multi-arch.
• Silent cache mismatches: clear or segregate caches per platform (--cache-to/--cache-from).
• Mixing CPU-specific binaries: ensure the binary copied into the final image matches TARGETARCH.

Performance notes

• Emulation (running amd64 on arm64 or vice versa) is much slower and can increase memory usage. Prefer native images when possible.
• Cross-building with QEMU is slower than native builds. For CI, consider native runners for each architecture or remote builders (e.g., separate amd64 and arm64 machines joined to one Buildx builder).
• Keep images small for faster pulls on all platforms: use minimal bases (alpine, distroless), multi-stage builds, and strip debug symbols.
• Leverage layer caching with Buildx: use registry cache (--cache-to type=registry,mode=max) to speed up multi-arch CI builds.

FAQ

• What does the error actually mean?

  • The registry’s manifest list for the tag does not include an entry matching your requested platform (e.g., linux/arm64), so Docker can’t select a compatible image.

• How do I see which architectures a tag supports?

  • docker buildx imagetools inspect IMAGE:TAG or docker manifest inspect IMAGE:TAG (for remote tags).

• How can I force a platform when running?

  • docker run --platform=linux/amd64 IMAGE:TAG (or arm64). Requires emulation if your host differs.

• I’m on Apple Silicon and need x86 images. Is that okay?

  • Yes, use --platform=linux/amd64. It will use emulation; expect slower performance. Prefer multi-arch images when available.

• How do I ensure my own images are multi-arch?

  • Build with docker buildx build --platform linux/amd64,linux/arm64 --push ... and verify with imagetools inspect.