Docker Registry "500 Internal Server Error" / Unexpected HTTP Status
By Daniel Zoghalchali·Latchkey
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.
Frequently asked questions
What causes ""received unexpected HTTP status: 500""?
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.
How do I fix "received unexpected HTTP status: 500"?
Because the failure is transient and server-side, a bounded retry usually succeeds without other changes.
Can Latchkey fix this automatically?
Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.
