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
Diagnose it: read the container, not the compose file
A container that exits immediately in CI has almost always logged the reason and then been cleaned up. Capture the logs and the exit code before changing configuration.
Terminal
# why did it stop?
docker ps -a --format '{{.Names}}\t{{.Status}}\t{{.Image}}'
docker logs <container> 2>&1 | tail -50
docker inspect <container> --format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}'
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 Docker "image found but does not match the specified platform"?
There are 2 common causes: cached image is a different architecture and single-arch image used on a mixed pipeline. A previous pull cached the amd64 variant; a later request for arm64 (or a different OS) does not match the cached single-arch image.
How do I fix Docker "image found but does not match the specified platform"?
There are 2 fixes depending on which cause you have: pull the matching platform explicitly and publish a multi-arch image. Work through them in order, since the first is the most common.
What does Docker "image found but does not match the specified platform" actually mean?
A pull or run warns/fails with image with reference ...
How do I stop Docker "image found but does not match the specified platform" happening again?
Publish multi-arch manifest lists for images used across platforms. The prevention section lists 3 changes that keep it from recurring.
