Introduction

The Docker error unknown blob usually appears when a registry manifest points to a layer digest that the registry cannot return. That means the client is asking for a valid-looking image, but one of the content-addressed objects behind that image is missing, inaccessible, or out of sync with the manifest metadata.

What a Blob Is in Docker Terms

Docker images are built from content-addressed objects. Each layer and the image configuration object is stored in the registry by digest, such as sha256:.... Those stored objects are often called blobs.

When you pull an image, the client first downloads the manifest, then fetches each referenced blob by digest. If the manifest says a layer exists but the registry cannot serve it, the pull fails with unknown blob.

A quick inspection command is:

docker manifest inspect my-registry.example.com/team/app:latest

If the manifest exists but the pull still fails, the problem is often one of these:

• the image push was interrupted and the manifest was published before all layers were durable
• registry garbage collection removed a blob that a tag still references
• a CDN, proxy, or mirror is serving stale manifest data
• the tag was overwritten while another replica still serves older layer references

Start by Verifying Whether the Tag or Digest Is Broken

Tags are mutable, so they can hide replication or caching issues. If you know the exact digest that should exist, try pulling by digest instead of by tag.

docker pull my-registry.example.com/team/app@sha256:0123456789abcdef

If the digest pull works and the tag pull fails, the registry metadata around the tag is likely inconsistent. If both fail, the underlying blob probably is really missing.

It also helps to retry with fresh authentication, especially with private registries where permissions can differ between repositories and blobs.

docker logout my-registry.example.com
docker login my-registry.example.com
docker pull my-registry.example.com/team/app:latest

Authentication is not the most common cause of unknown blob, but it is cheap to rule out.

Fix the Registry Side, Not Just the Client

Client cleanup commands are useful when local metadata is stale, but most real unknown blob incidents originate on the registry side. If you control the image pipeline, the safest repair is often to rebuild and push the image again so the manifest and all referenced blobs are republished together.

1docker build -t my-registry.example.com/team/app:2026-03-11 .
2docker push my-registry.example.com/team/app:2026-03-11
3docker tag my-registry.example.com/team/app:2026-03-11 my-registry.example.com/team/app:latest
4docker push my-registry.example.com/team/app:latest

If you run a private registry, inspect whether garbage collection or retention policies removed layers that were still referenced. That can happen after manual deletions, aggressive cleanup jobs, or a failed registry migration.

In mirrored or replicated registries, wait for replication to finish before promoting tags. A tag that becomes visible on one node before all blobs arrive on another node is a classic source of intermittent pull failures.

When Client Cleanup Helps

If the registry is healthy, local cache state may still be confusing the client. In that case, remove the broken local copy and pull again.

docker image rm my-registry.example.com/team/app:latest
docker system prune --volumes

Use pruning carefully on shared build agents, but it can help if a corrupted local layer or stale cache is involved.

For CI systems, the better pattern is to use immutable tags tied to a build number or commit SHA. That reduces the chance of workers seeing a moving latest tag whose underlying content changed mid-rollout.

Common Pitfalls

A common mistake is assuming the local Docker daemon is at fault every time. In reality, unknown blob often means the registry metadata is inconsistent or incomplete.

Another mistake is continuing to reuse mutable tags during an outage. If latest was published from a half-finished push, retrying the same mutable tag across many clients spreads the problem instead of isolating it.

Teams also get into trouble when they run registry garbage collection without understanding whether manifests, tags, and blobs are still referenced. Storage cleanup is safe only when the registry has a correct view of reachability.

Finally, do not confuse unknown blob with image-not-found errors. If the tag exists but one layer does not, the problem is deeper than a simple typo in the repository name.

Summary

• A Docker blob is a content-addressed layer or config object stored by digest.
• 'unknown blob means the manifest references an object the registry cannot serve.'
• Check whether the problem is limited to a mutable tag or affects the exact digest too.
• Re-pushing the image is often the fastest repair when you control the pipeline.
• Registry garbage collection, replication lag, and stale caches are common root causes.