CI "502 Bad Gateway" / "503 Service Unavailable" from a Mirror

By Kaveh Alemi·Latchkey

A mirror or proxy returned a 502 or 503 - a server-side, transient failure. A 502 means an edge/gateway could not reach its origin; a 503 means the service shed the request under load. Both clear on retry.

What this error means

A dependency download or index fetch from a mirror fails with 502 Bad Gateway or 503 Service Unavailable. The same request succeeds seconds to minutes later once the upstream recovers - the hallmark of a transient 5xx.

CI log

Failed to fetch https://mirror.example.com/.../pkg.tar.gz  502  Bad Gateway
# or
The repository ... returned 503 Service Unavailable

Common causes

An edge/gateway node could not reach its origin (502)

A CDN or reverse proxy returns 502 when its upstream origin is momentarily unreachable or erroring. A retry routes to a healthy node and succeeds.

The mirror shed the request under load (503)

Under heavy load a mirror returns 503 to protect itself. It is transient by definition and clears as load drops.

How to fix it

Retry with backoff

A transient 5xx is the ideal retry candidate.

Terminal

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

Reduce dependence on one mirror

Enable the package manager’s built-in retries (apt Acquire::Retries, etc.).
Front the upstream with a pull-through cache so repeat fetches do not hit the flaky mirror.
Pull from an alternate/closer mirror when one is unhealthy.

How to prevent it

Enable package-manager retries by default in CI.
Front mirrors 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 502/503?

Yes - these are transient server-side errors, and package fetches are idempotent reads. The only risk is retrying forever; a bounded retry with backoff fails clearly if the mirror is genuinely down.

References

GitHub Actions documentation