Docker "received unexpected HTTP status: 503 Service Unavailable" in CI

The registry (or a proxy in front of it) answered with 503 Service Unavailable. The request reached the server and it declined, temporarily: the backend is overloaded, in maintenance, or rate limiting, so retrying after a delay often succeeds.

What this error means

docker pull or push fails with "received unexpected HTTP status: 503 Service Unavailable", sometimes intermittently under load.

failed to solve: failed to push registry.corp.example/app:latest:
received unexpected HTTP status: 503 Service Unavailable

Common causes

The registry backend is overloaded or in maintenance

A 503 is the server saying it cannot serve right now, commonly during load spikes or maintenance windows.

A proxy or gateway returns 503 for the upstream

A reverse proxy in front of the registry can emit 503 when the upstream is unhealthy or unreachable.

How to fix it

Retry with backoff

Because 503 is temporary, retry the pull or push after a short delay so a transient outage clears.

for i in 1 2 3 4 5; do docker push "$IMAGE" && break; sleep 15; done

Confirm the registry health

Check the registry endpoint directly to distinguish a brief blip from a sustained outage before escalating.

curl -sI https://registry.corp.example/v2/ | head -1

How to prevent it

• Add retries with backoff around registry pulls and pushes.
• Use a pull-through cache so a registry blip does not stop every job.
• Watch registry status and avoid deploy waves during known maintenance windows.

Related guides