Docker "blob upload unknown" (registry push interrupted) in CI

By Kaveh Alemi·Latchkey

A registry push uploads each layer as a chunked blob session. If that session is interrupted - a dropped connection, a timeout, or an upload that expired server-side - the registry no longer knows the in-progress upload and responds blob upload unknown. This is almost always a transient network/registry failure that clears on retry.

What this error means

A docker push fails partway with blob upload unknown to registry. A re-push usually resumes and completes.

failed to push myorg/api:1.4.2: blob upload unknown to registry

Common causes

A dropped or timed-out upload session

A network interruption mid-upload invalidates the chunked blob session.

A server-side expired upload

A slow upload can exceed the registry's session lifetime, leaving it unknown.

How to fix it

Re-run the push

1. Retry - interrupted blob uploads are transient and resume cleanly.

docker push ghcr.io/myorg/api:1.4.2

Reduce upload size and contention

1. Slim layers so each blob uploads within the session lifetime.
2. Avoid pushing many large images concurrently over a constrained link.

docker history ghcr.io/myorg/api:1.4.2
docker buildx prune -f

How to prevent it

• Retry interrupted pushes before investigating.
• Keep layers small so uploads finish within session limits.
• Avoid saturating the link with concurrent large pushes.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation