attempting to update a git repository, but

Error message

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

What it means

The `fetch` helper in `src/sources/git/utils.rs` refuses to update a git repository because the global context reports an offline mode flag. Unlike error 140 (which fires at the source level for a specific checkout), this is the low-level guard inside the actual fetch routine and triggers on any attempt to mutate a git clone while offline. The `{offline_flag}` placeholder echoes the exact flag value (e.g. `--offline`).

Solutions

Run the same command without `--offline` (and ensure `CARGO_NET_OFFLINE` is unset) to let Cargo fetch.
Pre-populate the cache on a connected host via `cargo fetch`, then mirror `~/.cargo/git` to the offline host.
If you must stay offline, pin the git dependency (`rev` or `tag`) to a commit already in the local db and regenerate `Cargo.lock` accordingly.

Example fix

# before
cargo build --offline   # fails when clone is stale

# after
cargo fetch             # run online once
cargo build --offline   # now succeeds against populated cache

Defensive patterns

Strategy: validation

Validate before calling

// Check offline flag before invoking any flow that calls git::utils::fetch.
fn safe_fetch_precheck(gctx: &GlobalContext) -> Result<(), anyhow::Error> {
    if gctx.offline_flag().is_some() {
        anyhow::bail!("refusing to call git fetch: offline mode is active; run without --offline or pre-fetch");
    }
    Ok(())
}

Type guard

fn can_fetch_online(gctx: &GlobalContext) -> bool {
    gctx.offline_flag().is_none() && gctx.network_allowed()
}

Try / catch

if let Err(e) = git::utils::fetch(&mut repo, url, &manifest_ref, &locked_ref, gctx, kind) {
    if e.to_string().contains("was specified") {
        // offline guard fired: degrade to cached-only or ask user
    }
    return Err(e);
}

Prevention

Do not pass `--offline` unless you have already fetched all git deps.
Gate programmatic fetches behind a `network_allowed()` check.
Maintain a warm `~/.cargo/git` cache for offline builds.
Surface clear UI when offline blocks an update.

When it happens

Trigger: Any code path that calls `git::utils::fetch(...)` while `gctx.offline_flag()` returns `Some`. This happens when Cargo needs to update a git dependency index/clone and `--offline` or `CARGO_NET_OFFLINE=true` is set, and no earlier short-circuit (locked+present, github fast-path cache hit) applied.

Common situations: Building with `--offline` after a dependency's branch moved and the local clone is behind; `cargo update -p <git-dep>` issued under offline; transitioning a project from networked to offline CI without first running `cargo fetch`.

Related errors

AI-assisted analysis of rust-lang/cargo@495c385d08 (2026-08-11). Data as JSON: /api/errors/26bb0ac5727e1db5. Report an issue: GitHub.

Appendix: 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 495c385d08)