Docker "blob unknown to registry" on Push - Fix Cross-Repo Layer Mounts
During a push, the registry reported that a layer blob it was told to expect is unknown. Usually a cross-repository layer mount failed, or the blob was pruned/never fully uploaded.
What this error means
A docker push fails partway with blob unknown to registry (or BLOB_UNKNOWN). It can be transient (eventual consistency on a distributed registry) or persistent (a layer genuinely missing).
failed to push manifest: manifest blob unknown: blob unknown to registry
# or per-layer:
unknown blob sha256:9f2c... : blob unknown to registryCommon causes
A cross-repo layer mount was assumed but failed
Registries optimize pushes by mounting an existing layer from another repo. If the source layer was removed or the mount lacked permission, the manifest references a blob the registry does not actually have.
Eventual consistency on a distributed registry
On a registry backed by object storage, a freshly-uploaded blob may not be visible yet when the manifest is committed, surfacing as "blob unknown" transiently.
A referenced base/cache blob was garbage-collected
Aggressive registry GC can delete a layer that an in-flight push expected to reuse.
How to fix it
Retry the push; force a full re-upload if it persists
A transient consistency issue clears on retry; a persistent one needs the layers re-pushed without relying on a cross-repo mount.
for i in 1 2 3; do docker push myorg/api:1.4.2 && break; sleep $((i*10)); done
# if it persists, rebuild --no-cache so all layers are uploaded fresh
docker build --no-cache -t myorg/api:1.4.2 . && docker push myorg/api:1.4.2Avoid relying on pruned cross-repo layers
- Confirm the source repo of any mounted layer still exists.
- Re-tag and push the full image rather than depending on shared blobs.
- Loosen registry GC so in-use layers are not pruned mid-pipeline.
How to prevent it
- Wrap pushes in a bounded retry for distributed-registry consistency.
- Do not depend on cross-repo layer reuse for repos that get pruned.
- Tune registry garbage collection to keep referenced blobs.