CI Transient 5xx from Package Mirror - 502/503/504 on Install

A package mirror or registry returned a 5xx server error. These are server-side, transient by definition, and almost always succeed when the same request is retried seconds later.

What this error means

A dependency install or image pull fails with 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout from a mirror or registry. The same workflow passes minutes later once the upstream recovers.

CI log

Failed to fetch https://deb.example.com/.../Packages  503  Service Unavailable
# or
received unexpected HTTP status: 502 Bad Gateway

Common causes

The upstream mirror was briefly overloaded

Mirrors and registries are shared infrastructure. Under load they shed requests with 502/503/504 - nothing to do with your build, and it clears as load drops.

A CDN or gateway node was momentarily unhealthy

A 502/504 often comes from an edge node failing to reach its origin. A retry routes to a healthy node and succeeds.

How to fix it

Retry with backoff

A transient 5xx is the ideal retry candidate - back off and try again.

Terminal

for i in 1 2 3 4 5; do
  curl -fsSL "$URL" -o out && break
  sleep $((i*i))   # exponential-ish backoff
done

Reduce dependence on a single mirror

Configure the package manager’s built-in retries (e.g. apt Acquire::Retries, npm fetch-retries).
Use a pull-through cache so repeat fetches do not hit the flaky upstream.
Mirror critical dependencies into a registry you control.

How to prevent it

Enable package-manager retries by default in CI.
Front upstreams with a pull-through cache or internal mirror.
Pin and cache dependencies so a mirror blip is non-blocking.

Frequently asked questions

Is it safe to auto-retry a 5xx?

Yes - 5xx server errors are transient and idempotent for reads like package fetches. The risk is only retrying forever; a bounded retry with backoff fails clearly if the upstream is genuinely down.