The Named Manifest Is Not Known to the Registry: Causes, Fixes, and Prevention
"The named manifest is not known to the registry" is the error Docker, Podman, and containerd return when a registry cannot resolve the image reference you requested. In plain terms, the client asked the registry for a specific manifest — the JSON document that describes an image's layers and configuration — and the registry answered that no such manifest exists under that name, tag, or digest. The good news is that this is almost always a reference or permission problem, not a broken engine. The bad news is that the message itself rarely tells you which part of the reference failed.
What a Manifest Is, and Why the Registry "Doesn't Know" It
Every container image is stored in two parts: the manifest, which is an index of metadata, and the blobs, which are the compressed filesystem layers. Worth adding: a manifest is addressed either by a mutable tag (nginx:1. 25) or by an immutable digest (nginx@sha256:4f4…).
How the Registry Handles a Manifest Request
When the client issues a request such as
GET /v2//manifests/
the registry looks up three pieces of information:
- Repository existence – does
<repository>have any entries at all? - Tag or digest match – is the requested identifier present in the repository’s manifest index?
- Access rights – does the authenticated user (or anonymous client) have permission to read that manifest?
If any of those steps fails, the registry returns an HTTP 404 (Not Found) or 401 (Unauthorized) response, which the Docker/Podman/containerd CLI interprets as “the named manifest is not known to the registry.” The error message itself is deliberately generic; the underlying HTTP status code and response body contain the real clue No workaround needed..
Typical Root Causes
| Category | Why it triggers the error | Example |
|---|---|---|
| Typographical mistake | A single character off in the repository or tag name makes the key invisible to the index. The request is rejected as “unknown.And com/db:prod` without a logged‑in session | |
| Registry version incompatibility | Older clients (Docker 17. Because of that, example. On the flip side, | After a registry cleanup, the client still tries to resolve a stale entry |
| Authentication / authorization | Anonymous access is denied for private registries; an expired token or missing credentials leads to a 401 response that the CLI treats as “manifest unknown. , after a re‑tag) results in a 404 because the exact digest is not stored under that repository. 0when the actual tag ismyapp:1` |
|
| Tag does not exist | Tags are mutable pointers; if the tag was never pushed or was later deleted, the manifest is absent. g.Worth adding: | Pulling nginx:latest from a private registry that only contains nginx:1. Because of that, 25 |
| Digest mismatch | Using a digest that points to a different manifest (e. And | docker pull myrepo/app@sha256:abcd… when the digest belongs to a different repository |
| Cache staleness | Local Docker config caches a manifest index that no longer reflects recent changes on the remote registry. Because of that, | `docker pull myapp:1. But x) speak the v2‑schema‑1 API, while a modern registry may only support v2‑schema‑2 manifests. Here's the thing — ” |
| Content‑trust enforcement | With DOCKER_CONTENT_TRUST=1, the client expects a signed manifest; a missing signature causes the registry to reject the request. ” |
`docker pull private. |
| Network or proxy interference | A corporate proxy strips the Docker‑Content‑Trust header or returns an HTML error page, which the client cannot parse as a manifest. |
Immediate Fixes
-
Verify the exact reference
- Run
docker imagesorpodman imagesto see locally cached tags. - Use
curl -I https://registry.example.com/v2/<repo>/manifests/<tag>(or the appropriate digest) to inspect the HTTP status directly.
- Run
-
Log in to the registry (if it is private)
docker login registry.example.com # or podman login registry.example.comEnsure the credentials are current; re‑authenticate after password changes Worth knowing..
-
Clear the local manifest cache
docker system prune -a --volumes # removes all unused images and cached manifests # or, more surgically: rm -rf ~/.docker/metadata/* # Docker 20.10+ stores cache here -
Pull using the immutable digest
If you have the correct
digest, reference it explicitly to bypass tag resolution entirely:
docker pull myrepo/app@sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
Digests are content-addressed and immutable, so they sidestep the mutable-tag problem described above.
-
Inspect the manifest directly with the registry API
# Fetch the manifest and see the raw response curl -sSL \ -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \ -H "Accept: application/vnd.oci.image.manifest.v1+json" \ https://registry.example.com/v2//manifests/ | jq . A
404with a JSON body of{"errors":[{"code":"MANIFEST_UNKNOWN", ...}]}confirms the tag or digest genuinely does not exist server-side, distinguishing a real "missing" from a client-side cache or auth problem. -
Query the tag list to confirm what actually exists
curl -sSL https://registry.example.com/v2//tags/list | jq . This returns every tag the registry currently holds for the repository. If your expected tag is absent, the reference is wrong or was deleted; if it is present, the problem lies in authentication, caching, or client configuration instead.
Preventing Recurrence
The "manifest unknown" error is almost always a symptom of a mismatch between what the client thinks exists and what the registry actually stores. A few habits eliminate the majority of cases:
- Pin to digests in production. Tags are convenient for humans but mutable by design. Deployment manifests, CI pipelines, and infrastructure-as-code should reference
@sha256:…digests so that "what you tested" is provably "what you run." - Automate re-authentication. Expired tokens masquerade as missing manifests. Use credential helpers (
docker-credential-*) or short-lived tokens from your CI secret store rather than long-lived passwords that silently lapse. - Keep clients current. Schema-1 deprecation means older Docker versions increasingly fail against modern registries. Standardize on a supported client version across developer machines and build agents.
- Separate registry namespaces deliberately. Avoid promoting the same tag across environments without an explicit, auditable copy step (
docker buildx imagetools createorcrane copy). Silent re-tagging is a common root cause of digest mismatches. - Make proxies registry-aware. If you pull through a corporate proxy or mirror, ensure it forwards the
AcceptandAuthorizationheaders intact and does not intercept registry responses with HTML error pages.
Conclusion
"Manifest unknown" is deceptively simple: the registry reports that the object you asked for does not exist, yet the message conflates several distinct failure modes. Consider this: a missing tag, a mismatched digest, a stale local cache, an expired credential, an outdated client, or an interfering proxy can all surface as the same opaque error. The practical path forward is to work outward from the reference itself—confirm the tag or digest exists via the registry API, verify your authentication, clear stale local state, and pin to immutable digests where correctness matters. Treated this way, the error stops being a mystery and becomes a quick, deterministic diagnosis: either the object is genuinely absent, or something between your client and the registry is lying about it.