Technology · PRACTICAL GUIDE
Docker pull says ‘manifest unknown’? Prove the remote reference before clearing anything
Capture the expanded registry, repository, tag or digest. Prove the remote descriptor and authenticated view before pruning local images, changing platform flags or republishing anything.
‘Manifest unknown’ is not a generic local Docker failure. The Registry V2 specification says the requested manifest, identified by repository name and tag, is unknown to that repository.
Preserve the exact expanded reference, query the tag or digest, then separate registry view from platform selection. That order prevents cache cleanup from hiding the evidence.
Capture the exact expanded image reference
Copy the full error and the exact command, Compose service or deployment field that produced it. Record the registry host, namespace, repository, tag or digest, and print any CI variables before changing them.
Do not start by pruning images or clearing the builder cache. MANIFEST_UNKNOWN is a registry response about the requested remote name and tag; deleting local layers cannot create that remote manifest.
Resolve defaults that hide in a short name
Write the reference in four parts: registry, repository path, image name and tag. If no tag is written, Docker normally asks for latest; a repository can exist without publishing that tag.
Compare the literal characters, including case, separators and CI substitutions. A successful login or the existence of another tag proves access to some registry content, not that this exact reference exists.
Query the tag and descriptor before pulling
Use the registry UI or an authenticated manifest-inspection command to test the exact tag. Record the returned digest and media type. If the tag is absent, choose an existing immutable tag or fix the publisher; do not invent a digest.
If a digest is already pinned, query that digest directly. A tag can move while a digest is content-addressed, so test them separately and preserve the failing reference in the incident record.
Separate tag lookup from platform selection
When the tag resolves to an image index, inspect its descriptors for the required OS and architecture. A present tag with no matching platform is a different failure branch from MANIFEST_UNKNOWN for the name and tag.
Do not assume arm64, amd64 or Windows variants exist because another platform pulls successfully. Publish the missing variant, select a supported tag, or change the target platform only when that matches the workload.
Audit CI, mirrors and private-registry views
If the reference works interactively but fails in CI, compare the expanded string, credentials, registry hostname, proxy and network path. A mirror or pull-through cache can expose a different view from the origin.
Finish with one proof: the exact tag or digest resolves from the same runtime and registry path that failed. Record the descriptor digest and platform, then pin an immutable reference where reproducibility matters.
