cargo "can't find ... in --offline mode" (cache miss) in CI

You built with --offline (or --frozen), so cargo refuses to touch the network. A crate the lockfile needs is not in the local registry cache, so cargo cannot proceed and tells you to run without --offline or to pre-fetch.

What this error means

cargo build --offline fails with "error: no matching package named X found ... in the offline mode" or "can't fetch X in the offline mode" naming a crate not in the cache.

error: failed to download `serde v1.0.203`
Caused by:
  attempting to make an HTTP request, but --offline was specified

Common causes

The crate was never fetched into the cache

A dependency was added or bumped since the cache was warmed, so the offline build has no copy of it.

A cache restore that missed or used a stale key

The cache key did not change with Cargo.lock, so an outdated cache was restored that lacks the new crates.

How to fix it

Pre-fetch with the network, then build offline

1. Run cargo fetch --locked in a step that has network access.
2. Build with --offline so the resolved cache is used.
3. Key the cache on Cargo.lock so it changes when dependencies do.

cargo fetch --locked
cargo build --offline --locked

Fix the cache key to track the lockfile

Make the cache invalidate whenever dependencies change so the restored cache always matches the build.

key: cargo-${{ runner.os }}-${{ hashFiles('Cargo.lock') }}

How to prevent it

• Run cargo fetch with network before any --offline build.
• Key caches on Cargo.lock so they invalidate on dependency changes.
• Vendor dependencies if the build must be fully offline.

Related guides