Docker Registry "500 Internal Server Error" / Unexpected HTTP Status

A 5xx from the registry is a server-side failure, not your image. These are transient and usually clear on retry once the registry recovers.

What this error means

A push or pull fails partway with received unexpected HTTP status: 500 Internal Server Error (or 502/503). It is intermittent - re-running the same job minutes later often succeeds with no changes.

docker push/pull output

received unexpected HTTP status: 500 Internal Server Error
# or during a blob upload:
error parsing HTTP 503 response body: ... <html>503 Service Unavailable</html>

Common causes

Registry-side outage or overload

The registry (Docker Hub, GHCR, ECR, a self-hosted registry) returned a 5xx because it was degraded, rate-limiting at the edge, or mid-deploy. Nothing about your image is wrong.

Network proxy or load balancer hiccup

A proxy or load balancer between the runner and the registry can surface a 502/503 during a transient blip, which Docker reports as an unexpected HTTP status.

How to fix it

Retry with backoff

Because the failure is transient and server-side, a bounded retry usually succeeds without other changes.

Terminal

for i in 1 2 3; do
  docker push myorg/api:1.4.2 && break
  echo "push failed (attempt $i), retrying..."; sleep $((i*10))
done

Check status and fall back

Check the registry provider status page to confirm an incident.
If pulling base images, fall back to a mirror or your own registry cache.
Avoid pushing huge single layers that are more likely to time out mid-upload.

How to prevent it

Wrap pushes/pulls in a bounded retry with backoff.
Mirror critical base images so a Hub incident does not block builds.
Keep layers reasonably sized to reduce mid-upload failures.