Docker "image found but does not match the specified platform"

By Daniel Zoghalchali·Latchkey

A locally-cached image has a different platform than the one requested. Docker found the reference but refuses to use it because the OS/arch does not match.

What this error means

A pull or run warns/fails with image with reference ... was found but does not match the specified platform, or image operating system "linux" cannot be used on this platform. Often a cached amd64 image when arm64 was requested.

docker output

WARNING: image with reference myorg/api:1.4.2 was found but does not match the
specified platform: wanted linux/arm64, actual: linux/amd64

Common causes

Cached image is a different architecture

A previous pull cached the amd64 variant; a later request for arm64 (or a different OS) does not match the cached single-arch image.

Single-arch image used on a mixed pipeline

The image only exists for one platform, so any request for another platform cannot be satisfied from it.

How to fix it

Pull the matching platform explicitly

Force a fresh pull for the platform you need so the right variant is cached.

Terminal

docker pull --platform linux/arm64 myorg/api:1.4.2
docker run --platform linux/arm64 myorg/api:1.4.2

Publish a multi-arch image

Build and push a manifest list covering all target platforms (buildx --platform).
Inspect with docker buildx imagetools inspect to confirm both arches are present.
Remove stale single-arch cache (docker image rm) before re-pulling.

How to prevent it

Publish multi-arch manifest lists for images used across platforms.
Pull with an explicit --platform in mixed-arch pipelines.
Clear stale single-arch cache when switching target platforms.

Frequently asked questions

What causes ""does not match platform""?