rust-lang/cargo · error · anyhow::Error

can't checkout from '{}': you are in the offline mode ({offl

Error message

can't checkout from '{}': you are in the offline mode ({offline_flag})

What it means

Cargo refuses to update/checkout a git dependency because the process is running with `--offline` or `--frozen` (the `{offline_flag}` value). It fires in `GitSource::blockish_get` once Cargo has exhausted every local option: the locked revision isn't present in the on-disk git database, or a deferred branch/tag/reference can't be resolved from the existing clone, so resolving it would require hitting the network — which the flag forbids. The remote URL that Cargo wanted to fetch from is interpolated into the message.

Source

Thrown at src/sources/git/source.rs:219

                    .gctx
                    .offline_flag()
                    .expect("always present when `!network_allowed`");
                let rev = db.resolve(&git_ref).with_context(|| {
                    format!(
                        "failed to lookup reference in preexisting repository, and \
                         can't check for updates in offline mode ({offline_flag})"
                    )
                })?;
                (db, rev)
            }

            // ... otherwise we use this state to update the git database. Note
            // that we still check for being offline here, for example in the
            // situation that we have a locked revision but the database
            // doesn't have it.
            (locked_rev, db) => {
                if let Some(offline_flag) = self.gctx.offline_flag() {
                    anyhow::bail!(
                        "can't checkout from '{}': you are in the offline mode ({offline_flag})",
                        self.remote.url()
                    );
                }

                if !self.quiet {
                    let scope = if is_submodule {
                        "submodule"
                    } else {
                        "repository"
                    };
                    self.gctx
                        .shell()
                        .status("Updating", format!("git {scope} `{}`", self.remote.url()))?;
                }

                trace!("updating git source `{:?}`", self.remote);

View on GitHub (pinned to 0e07a15537)

Solutions

1. Run once WITHOUT the flag (e.g. plain `cargo fetch`) so the git database under `~/.cargo/git/db/` is populated, then retry with `--offline`.
2. If you must stay offline, vendor the dependency (`cargo vendor`) and add a `[source]` replacement mapping the git URL to the vendored path.
3. Pin the dependency to a concrete `rev = "<full 40-char commit hash>"` that you have verified is already present in the local git cache.
4. For `--frozen`: refresh `Cargo.lock` on a networked machine and commit it, so the frozen build never needs a fresh fetch.
5. Remove `net.offline = true` from `.cargo/config.toml` if it was set globally and is no longer intended.

Example fix

# before
cargo build --offline   # git dep 'foo' locked rev not in cache -> error

# after (option A: populate then offline)
cargo fetch && cargo build --offline

# after (option B: vendor)
cargo vendor vendored
# .cargo/config.toml
[source.my-git-dep]
git = "https://github.com/org/foo"
replace-with = "vendored-sources"
[source.vendored-sources]
directory = "vendored"

# Before building offline, confirm the git dep's locked OID is cached locally.
# (shell)
# 1. ensure you have network for the one-time populate
cargo fetch
# 2. only then go offline
cargo build --offline

# In Rust tooling that wraps cargo, check before invoking:
if offline_enabled && !git_db_has_oid(&db, locked_oid) {
    return Err(format!("git dep {dep} not cached; cannot build --offline"));
}

When it happens

Trigger: Running `cargo build --offline` / `cargo build --frozen` (or having `net.offline = true` in config) when (a) it's the first build of a git dependency, (b) `Cargo.lock` was updated to point at a newer git commit than what's cached in `~/.cargo/git/db/`, or (c) the git reference (`branch`/`tag`/`rev`) can't be resolved against the locally cloned database. Reached via the `(locked_rev, db) =>` arm at src/sources/git/source.rs:217.

Common situations: CI pipelines that pass `--frozen`/`--offline` for reproducibility but forgot to populate or vendor the git sources; air-gapped build machines; switching git branches of the consuming project so `Cargo.lock` references an uncached OID; git dependency using `branch = "main"` while offline so the deferred ref can't be resolved.

Related errors

• attempting to update a git repository, but {offline_flag} wa
• config.json not found
• remote registries must have config
• subcommand is required, add a subcommand to the command alia
• alias {} has unresolvable recursive definition: {} -> {}

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/8d1277aeeb05ef67.json. Report an issue: GitHub.