cargo "failed to download" in CI: network and registry debugging

TL;DR

Cargo download failures in CI are network or registry configuration: the runner cannot reach crates.io (or the mirror), the registry config in the image is wrong, or a lockfile references a yanked version. Check connectivity to the registry first, then verify the registry configuration cargo actually uses in CI (not the one on your laptop).

The query

cargo "failed to download" in CI: how to download

Use this when

• CI cargo builds fail downloading crates
• Local builds fetch fine
• Registry or mirror configuration is involved
• After changing CI images or networks

Not for when

• Rust compile errors
• Dependency version conflicts (resolve errors, different)
• Local cargo issues

Steps

Step 1: Test registry connectivity from the runner

Fetch a small crate or query the registry API from the CI environment. Egress proxies and firewalls block crates.io in ways that look like cargo bugs. Confirm the network path before touching config. Expected output: registry reachable, or the network block found.

Step 2: Check which registry cargo uses in CI

Inspect cargo's registry configuration as resolved in the CI environment: config files, environment variables, sparse vs git protocol. CI images often carry stale or different registry config than developer machines. Expected output: the effective registry configuration known.

Step 3: Verify the lockfile against the registry

A lockfile pinning a yanked crate version fails downloads even with perfect connectivity. Check whether the failing crate version was yanked, and update the lockfile if so. Expected output: yanked versions identified and updated.

Step 4: Configure a registry mirror if needed

For restricted networks, point cargo at an internal mirror or vendored sources. Vendoring (cargo vendor) removes the network dependency entirely for reproducible builds. Expected output: downloads working through the mirror, or vendored with no network need.

Step 5: Cache the registry between runs

Cache the cargo registry and git checkouts in CI so downloads are rare. Fewer downloads mean fewer chances for transient failures, and faster builds as a bonus. Expected output: most builds fetching nothing; download failures nearly eliminated.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_n8HKu17guzgkB1Jy-jrXHw