Technology · PRACTICAL GUIDE
Docker says no matching manifest? Prove the requested platform before forcing architecture
Bind the host or override request to the tag's immutable image index, OS, architecture and variant before choosing a digest, republishing an image or enabling emulation.
“No matching manifest” means Docker could not join an effective platform request to a compatible descriptor in the referenced image index. It does not, by itself, prove that your laptop is wrong or that `--platform linux/amd64` is safe. Preserve both sides of the match first.
Freeze the exact request and image reference
Save the failing command, full error, image reference, Docker and Compose versions, active context, client/daemon architecture and every platform override in environment, Compose and build configuration. Keep the exact tag or digest. Do not add `--platform` yet: that changes the question you are debugging.
Inspect the immutable index
Run the supported image-index inspection command for the exact registry reference. Record the index media type and digest plus every descriptor's digest, OS, architecture and variant. If the reference resolves to one manifest rather than an index, record that too. Repeat against the registry you actually use, not a similarly named public tag.
Join request to descriptor
Compare the effective request tuple with the descriptors exactly. `linux/amd64` does not match `linux/arm64`; arm variants can matter; unknown-platform attestations are not runnable variants. If no descriptor matches, separate a publisher omission from a client request altered by a context, environment variable or service-level platform.
Choose the remedy by ownership
If a native descriptor exists, pin its digest or correct stale selection policy. If the publisher owns the image and the variant is missing, rebuild that platform and publish one complete index. If a foreign architecture is intentional, declare emulation explicitly and test it. If no supported variant exists, choose a compatible tag instead of pretending the mismatch disappeared.
Bind deployment to reviewed bytes
Record the selected platform-specific digest and, where useful, the parent index digest. Update Compose, CI or deployment policy so the platform choice is visible and reproducible. Treat tag-only repair as provisional because tags can move between inspections.
Prove runtime architecture and repeatability
Pull from a clean cache, inspect the resulting image digest and architecture, start the intended workload, and verify its reported machine architecture and health. Repeat on every supported host family. Stop if Docker selects a different digest, emulation is implicit, the index changes during rollout or the publisher cannot explain a missing variant.
