Harbor "blob upload unknown" on push in CI
A chunked blob upload uses a session id the registry tracks. "blob upload unknown" means the registry no longer recognizes that upload session, usually because it timed out, the backend storage hiccupped, or a proxy dropped the request. Retry the push to start fresh upload sessions.
What this error means
docker push to Harbor fails mid-upload with "blob upload unknown to registry" or "BLOB_UPLOAD_UNKNOWN", sometimes behind a reverse proxy or load balancer.
failed to push layer: blob upload unknown to registryCommon causes
The upload session expired or was dropped
A long pause, a timeout, or a proxy terminating the connection invalidates the upload id the client tries to continue.
A misconfigured proxy in front of Harbor
A reverse proxy with a small body limit or short timeout breaks chunked uploads, losing the session.
How to fix it
Retry the push to recreate sessions
- Re-run the push so new upload sessions are created.
- If it recurs at the same layer, suspect a proxy timeout or size limit.
- Raise proxy body-size and timeout limits in front of Harbor.
docker push harbor.example.com/team/app:latestTune the reverse proxy for large uploads
Increase client_max_body_size and read/send timeouts (for nginx) so chunked blob uploads complete.
client_max_body_size 0;
proxy_read_timeout 900;
proxy_send_timeout 900;How to prevent it
- Allow large request bodies and long timeouts on Harbor proxies.
- Retry transient upload-session failures.
- Keep Harbor storage backend healthy to avoid dropped sessions.