Registry "image's platform ... does not match the specified platform" in CI

By Kaveh Alemi·Latchkey

You requested an image for one platform but the registry only has it for another, so docker warns or errors that the platform does not match. Either the image is single-arch (no manifest list) or it lacks the architecture the runner needs. Build/push a multi-arch image or pull the matching platform.

What this error means

docker pull or run fails with "image's platform (linux/amd64) does not match the specified platform (linux/arm64)" or "no matching manifest for linux/arm64 in the manifest list entries".

WARNING: image's platform (linux/amd64) does not match the specified
platform (linux/arm64) and no specific platform was requested
no matching manifest for linux/arm64/v8 in the manifest list entries

Common causes

The image is single-architecture

The repository holds only one platform variant, so a runner on a different architecture finds no matching manifest.

The needed platform was never built/pushed

A multi-arch build omitted the runner architecture, so the manifest list has no entry for it.

How to fix it

Build and push a multi-arch manifest list

1. Set up buildx/QEMU.
2. Build for every platform you pull (e.g. amd64 and arm64) and push as one manifest list.
3. Pull again; the runner architecture now resolves.

docker buildx build --platform linux/amd64,linux/arm64 \
  -t registry.example.com/app:latest --push .

Pull the platform that exists

If multi-arch is not feasible, pull the specific available platform explicitly so docker does not pick a mismatched default.

docker pull --platform linux/amd64 registry.example.com/app:latest

How to prevent it

• Build multi-arch images covering every runner architecture you use.
• Match --platform on pull to what the registry actually holds.
• Verify manifest list entries before relying on a platform.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation