Cargo "can't be downloaded ... required for offline mode" in CI

You built with --offline (or CARGO_NET_OFFLINE=true) but a needed crate isn’t in the local cache. Cargo refuses to reach the network in offline mode, so it fails instead of downloading.

What this error means

A build that passed with network access fails under --offline saying a crate "can't be downloaded ... required for offline mode but it is not cached". It surfaces after a dependency change without re-running cargo fetch.

cargo output

error: failed to download `once_cell v1.19.0`

Caused by:
  attempting to make an HTTP request, but --offline was specified
  required for offline mode but it is not cached

Common causes

Crate not in the local cache

Offline mode can only use crates already in ~/.cargo/registry. A newly added or bumped dependency that was never fetched isn’t there.

Cache restored without the needed crate

A CI cache keyed on a stale Cargo.lock restores an old set of crates that predates the dependency change, so the new one is missing.

How to fix it

Fetch before building offline

Run cargo fetch with network access once, then build offline against the populated cache.

Terminal

cargo fetch --locked     # online, fills the cache
cargo build --offline    # now succeeds

Key the cache on the current lockfile

Make sure the registry cache key tracks Cargo.lock so it’s rebuilt when dependencies change.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.cargo/registry
    key: cargo-${{ hashFiles('Cargo.lock') }}

How to prevent it

Run cargo fetch (online) before any --offline build.
Key the cargo cache on Cargo.lock so it invalidates on dependency changes.
Drop --offline if you don’t intend to vendor or prefetch.