CI 503/502 from a Package Registry

By Kaveh Alemi·Latchkey

A 5xx from a registry is a server-side, transient error, the registry or its gateway was briefly unavailable. It is retryable and not a problem with your request.

What this error means

An install fails with 503 Service Unavailable or 502 Bad Gateway from the registry. Re-running the unchanged job typically succeeds once the upstream recovers.

shell

npm error code E503
npm error 503 Service Unavailable - GET https://registry.npmjs.org/react

Common causes

The registry or its gateway was briefly down

A momentary outage or deploy on the registry side returns 502/503 until it recovers.

Upstream overload

A spike in traffic can make a registry shed load with 5xx for a short window.

How to fix it

Retry on 5xx

Client retries cover a transient upstream error.

shell

npm config set fetch-retries 5
npm config set fetch-retry-factor 2
npm ci

Reduce dependence on one upstream

Use a pull-through cache or private mirror.
Cache dependencies so a registry blip does not block the build.
Pin versions to reduce metadata round-trips.

How to prevent it

Configure retries for registry fetches.
Run a caching proxy/mirror for dependencies.
On managed runners, transient registry 5xx responses are detected and the job is automatically retried, so a one-off blip does not fail the build.

Frequently asked questions

What causes "503/502 from registry"?