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

attempting to update a git repository, but {offline_flag} wa

Error message

attempting to update a git repository, but {offline_flag} was specified

What it means

The low-level git fetch entry point `fetch()` (src/sources/git/utils.rs:1015) bails immediately when `GlobalContext::offline_flag()` returns `Some`, i.e. the user passed `--offline`/`--frozen` or set `net.offline`. Unlike error 160 (which fires at the source layer after local resolution fails), this one fires unconditionally at the start of *any* clone/update of a git repository — so it triggers whenever a git source actually needs to talk to the remote. The `{offline_flag}` token (e.g. `--offline`) is interpolated so the user knows which mechanism blocked the operation.

Source

Thrown at src/sources/git/utils.rs:1024

/// * Dispatches `git fetch` using libgit2, gitoxide, or git CLI.
///
/// The `remote_url` argument is the git remote URL where we want to fetch from.
///
/// The `remote_kind` argument is a thing for [`-Zgitoxide`] shallow clones
/// at this time. It could be extended when libgit2 supports shallow clones.
///
/// [`-Zgitoxide`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#gitoxide
#[tracing::instrument(skip_all)]
pub fn fetch(
    repo: &mut git2::Repository,
    remote_url: &str,
    manifest_reference: &GitReference,
    locked_reference: &GitReference,
    gctx: &GlobalContext,
    remote_kind: RemoteKind,
) -> CargoResult<()> {
    if let Some(offline_flag) = gctx.offline_flag() {
        anyhow::bail!(
            "attempting to update a git repository, but {offline_flag} \
             was specified"
        )
    }

    let shallow = remote_kind.to_shallow_setting(repo.is_shallow(), gctx);

    // Flag to keep track if the rev is a full commit hash
    let mut fast_path_rev: bool = false;

    let oid_to_fetch = match github_fast_path(repo, remote_url, locked_reference, gctx) {
        Ok(FastPathRev::UpToDate) => return Ok(()),
        Ok(FastPathRev::NeedsFetch(rev)) => Some(rev),
        Ok(FastPathRev::Indeterminate) => None,
        Err(e) => {
            debug!("failed to check github {:?}", e);
            None
        }

View on GitHub (pinned to 0e07a15537)

Solutions

1. Drop the `--offline`/`--frozen` flag for this one command to allow the fetch.
2. Run `cargo fetch` on a networked host and copy `~/.cargo/git/` to the offline machine.
3. Vendor the git dependency and replace the source so `fetch()` is never called.
4. Set `CARGO_NET_OFFLINE=false` in the environment to override a config-level `net.offline=true`.

Example fix

# before
cargo update -p my-git-crate --offline   # -> attempting to update a git repository, but --offline was specified

# after
cargo update -p my-git-crate            # fetch the latest, then go offline

# Pre-flight: don't ask cargo to update git deps while offline.
if [[ "$CARGO_NET_OFFLINE" == "true" || " $CARGO_ARGS " == *" --offline"* ]]; then
  # populate cache first on a networked machine: cargo fetch
  :
fi

When it happens

Trigger: Calling `cargo update -p <git-crate>` while `--offline`/`--frozen`; a git submodule update path that routes through `fetch()`; any operation that calls `GitDatabase::checkout`/`fetch` when the local clone is stale or missing AND network is disabled. The guard is the very first statement in `fetch()`, so it cannot be bypassed by the caller.

Common situations: Same family as 160 but hit through the update/fetch code path rather than the source-resolve path: CI with `--frozen`, laptops in airplane mode with `net.offline=true`, mirror setups where the git remote is unreachable.

Related errors

• can't checkout from '{}': you are in the offline mode ({offl
• `{feature}` is unsupported when inferring the crate name, us
• invalid package name: `{url}` Use `cargo install --git {
• no path segments on url
• couldn't find username

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