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

By Daniel Zoghalchali·Latchkey

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.

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

Diagnose it: toolchain, features, or a stale target dir?

Cargo failures that only appear in CI are usually a different toolchain channel, a different feature set resolved by the dependency graph, or a target directory restored from a cache built with different flags.

rustc --version --verbose
cargo --version
cat rust-toolchain.toml 2>/dev/null

# which features actually got enabled across the graph?
cargo tree -e features | head -40

# rule out a poisoned cache before anything else
cargo clean && cargo build --locked

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.

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.

- 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.

Frequently asked questions

Related guides

References

• The Cargo Book
• GitHub Actions documentation