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

Error message

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

What it means

Cargo cannot fetch a git dependency because the user invoked it with an offline flag (`--offline`) while the locally cached git database does not contain the locked/required revision. The error fires in the fallthrough arm of `fetch_db` after Cargo confirmed the revision is missing locally and a network update would be required. The `{remote_url}` placeholder shows which git source failed.

Solutions

Remove `--offline` / unset `CARGO_NET_OFFLINE=true` and re-run so Cargo can fetch the missing commit.
Run `cargo fetch` (without `--offline`) on a networked machine to populate `~/.cargo/git/db`, then transfer or share that cache to the offline machine.
Pin the git dependency to a revision already present locally: inspect `~/.cargo/git/db/<repo>.db` with `git log` and update `rev = "..."` in `Cargo.toml` / `Cargo.lock` to match.
Clear the stale cache with `cargo cache --autoclean` (or remove `~/.cargo/git/db/<ident>`) then fetch online once to rebuild it.

Example fix

# before: Cargo.toml pins a commit not cached locally, run with --offline
[dependencies]
my-lib = { git = "https://github.com/user/repo", rev = "abc1234" }

# fix option 1: fetch online once
cargo fetch
# fix option 2: pin to a cached revision (find via: git --git-dir ~/.cargo/git/db/repo-*.db log)

Defensive patterns

Strategy: validation

Validate before calling

// Before building offline, verify the locked git revision is cached locally.
use std::process::Command;
fn ensure_git_rev_cached(repo_url: &str, rev: &str, cargo_home: &Path) -> std::io::Result<()> {
    let db_dir = cargo_home.join("git/db");
    let found = std::fs::read_dir(&db_dir)?.filter_map(Result::ok).any(|e| {
        let p = e.path();
        p.is_dir() && Command::new("git")
            .arg("--git-dir").arg(&p)
            .arg("cat-file").arg("-t").arg(rev)
            .output().ok().map_or(false, |o| o.status.success())
    });
    if !found { panic!("git rev {rev} of {repo_url} not in local cache; run `cargo fetch` online first"); }
    Ok(())
}

Type guard

fn offline_safe(lock_rev: &str, cargo_home: &std::path::Path) -> bool {
    // returns true if lock_rev appears in any cached git db
    std::fs::read_dir(cargo_home.join("git/db")).ok()
        .into_iter().flatten().filter_map(Result::ok)
        .any(|e| std::process::Command::new("git")
            .arg("--git-dir").arg(e.path())
            .arg("cat-file").arg("-t").arg(lock_rev)
            .output().ok().map_or(false, |o| o.status.success()))
}

Try / catch

match git_source.fetch_db(is_submodule) {
    Ok((db, rev)) => { /* use db */ },
    Err(e) => {
        let msg = e.to_string();
        if msg.contains("offline mode") {
            // prompt user to fetch online or pin to a cached rev
        }
        return Err(e);
    }
}

Prevention

Always run `cargo fetch` on a networked machine before going offline.
Pin git dependencies to tags or full commit hashes that you have fetched.
Mirror `~/.cargo/git` between networked and offline hosts.
In CI, cache `~/.cargo/git` across runs.

When it happens

Trigger: Calling a Cargo build/fetch command with `--offline` (or `CARGO_NET_OFFLINE=true`) when a git dependency's `Cargo.lock` pins a commit that is not present in the local `~/.cargo/git/db` cache. Also triggered when a previously locked revision was garbage-collected or the db was deleted.

Common situations: Running CI or building on an air-gapped machine with `--offline` after `Cargo.lock` was updated against a newer commit on a networked machine; switching branches whose `Cargo.lock` references a git commit never fetched locally; corrupted/pruned cargo git cache.

Related errors

AI-assisted analysis of rust-lang/cargo@eb98b54bc9 (2026-08-11). Data as JSON: /api/errors/8d1277aeeb05ef67. Report an issue: GitHub.

Appendix: 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 eb98b54bc9)