What This Error Means
Docker reached the registry over HTTP, but the registry or reverse proxy returned HTTP 503 because the service was unhealthy or overloaded.
Read this as a precise clue about which part of the workflow broke first. Once you know the failing layer, the fix path gets much shorter.
How to Fix It
If the registry is third-party, retry with backoff and confirm the outage is external before changing client config.
If the registry is self-hosted, check proxy health, backend health, and logs for the /v2/ request path.
Do not treat this as DNS or TLS unless the evidence changes, Docker already received an HTTP response.
Why It Happens
Usually this comes down to the registry or an upstream backend is overloaded, restarting, or in maintenance, a reverse proxy or ingress cannot reach the registry backend and surfaces that as HTTP 503, or a storage, auth, or backend dependency outage leaves the registry temporarily unavailable.
Verify the Fix
curl -i https://<registry>/v2/ returns a healthy status instead of HTTP 503, and re-run the original Docker pull or push and confirm it succeeds.
Prove it is HTTP 503, not a network failure
Reproduce the response outside Docker with curl -i https://<registry>/v2/ and confirm the server really returns HTTP 503.
Inspect response headers or body for proxy identifiers, retry hints, or upstream error details.
If this is your registry, check reverse-proxy and registry logs for the same time window as the failing request.
Examples
Error response from daemon: Get https://registry-1.docker.io/v2/: Service Unavailable
Error response from daemon: received unexpected HTTP status: 503 Service UnavailableHow registry 503 responses happen
This is the part worth understanding if the quick fix did not hold. It explains what Docker is trying to do at the moment the error appears.
A 503 response means Docker completed DNS, TCP, and TLS well enough to receive an HTTP response from the registry path.
The failure is therefore at the application layer:the registry, reverse proxy, or one of its dependencies is unhealthy, overloaded, or in maintenance.
Prevent It From Coming Back
To prevent this, monitor /v2/ health, backend readiness, and proxy error rates for self-hosted registries, and use retries with backoff in CI so short registry brownouts do not fail every build immediately.