Docker registry "500 Internal Server Error" in CI

By Kaveh Alemi·Latchkey

The registry returned a 5xx, meaning the failure is on the server side. These are transient blips, not a problem with your image or credentials, and usually succeed on retry.

What this error means

A pull or push fails with received unexpected HTTP status: 500 Internal Server Error (or 502/503). Re-running the same command shortly after often succeeds.

error: failed to push ghcr.io/org/app:latest:
received unexpected HTTP status: 500 Internal Server Error

Common causes

Registry-side outage or load

The registry hit an internal error or was overloaded when the request landed.

Large blob upload interrupted

A big layer push can trip a server-side timeout that surfaces as a 5xx.

How to fix it

Retry with backoff

1. Re-run the pull/push after a short wait; transient 5xx usually clears.

for i in 1 2 3; do docker push ghcr.io/org/app:latest && break; sleep $((i*5)); done

Reduce per-request load

1. Split very large images or push fewer tags at once.
2. Check the registry status page for an ongoing incident.

How to prevent it

• Wrap registry operations in a bounded retry. Self-healing managed runners such as Latchkey auto-retry transient registry 5xx blips automatically, so a momentary server error does not fail the job.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation