{"record":{"id":"26bb0ac5727e1db5","repo":"rust-lang/cargo","slug":"attempting-to-update-a-git-repository-but-offlin","errorCode":null,"errorMessage":"attempting to update a git repository, but {offline_flag} was specified","messagePattern":"attempting to update a git repository, but (.+?) was specified","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/sources/git/utils.rs","lineNumber":1024,"sourceCode":"/// * Dispatches `git fetch` using libgit2, gitoxide, or git CLI.\n///\n/// The `remote_url` argument is the git remote URL where we want to fetch from.\n///\n/// The `remote_kind` argument is a thing for [`-Zgitoxide`] shallow clones\n/// at this time. It could be extended when libgit2 supports shallow clones.\n///\n/// [`-Zgitoxide`]: https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#gitoxide\n#[tracing::instrument(skip_all)]\npub fn fetch(\n    repo: &mut git2::Repository,\n    remote_url: &str,\n    manifest_reference: &GitReference,\n    locked_reference: &GitReference,\n    gctx: &GlobalContext,\n    remote_kind: RemoteKind,\n) -> CargoResult<()> {\n    if let Some(offline_flag) = gctx.offline_flag() {\n        anyhow::bail!(\n            \"attempting to update a git repository, but {offline_flag} \\\n             was specified\"\n        )\n    }\n\n    let shallow = remote_kind.to_shallow_setting(repo.is_shallow(), gctx);\n\n    // Flag to keep track if the rev is a full commit hash\n    let mut fast_path_rev: bool = false;\n\n    let oid_to_fetch = match github_fast_path(repo, remote_url, locked_reference, gctx) {\n        Ok(FastPathRev::UpToDate) => return Ok(()),\n        Ok(FastPathRev::NeedsFetch(rev)) => Some(rev),\n        Ok(FastPathRev::Indeterminate) => None,\n        Err(e) => {\n            debug!(\"failed to check github {:?}\", e);\n            None\n        }","sourceCodeStart":1006,"sourceCodeEnd":1042,"githubUrl":"https://github.com/rust-lang/cargo/blob/495c385d0875c4ba51eb72ea0448a2d4c018b8d4/src/sources/git/utils.rs#L1006-L1042","documentation":"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`).","triggerScenarios":"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.","commonSituations":"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`.","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."],"exampleFix":"# before\ncargo build --offline   # fails when clone is stale\n\n# after\ncargo fetch             # run online once\ncargo build --offline   # now succeeds against populated cache","handlingStrategy":"validation","validationCode":"// Check offline flag before invoking any flow that calls git::utils::fetch.\nfn safe_fetch_precheck(gctx: &GlobalContext) -> Result<(), anyhow::Error> {\n    if gctx.offline_flag().is_some() {\n        anyhow::bail!(\"refusing to call git fetch: offline mode is active; run without --offline or pre-fetch\");\n    }\n    Ok(())\n}","typeGuard":"fn can_fetch_online(gctx: &GlobalContext) -> bool {\n    gctx.offline_flag().is_none() && gctx.network_allowed()\n}","tryCatchPattern":"if let Err(e) = git::utils::fetch(&mut repo, url, &manifest_ref, &locked_ref, gctx, kind) {\n    if e.to_string().contains(\"was specified\") {\n        // offline guard fired: degrade to cached-only or ask user\n    }\n    return Err(e);\n}","preventionTips":["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."],"tags":["cargo","git","offline","network","fetch"],"backgroundTag":null,"analyzedSha":"495c385d0875c4ba51eb72ea0448a2d4c018b8d4","analyzedAt":"2026-08-11T17:42:36.556Z","contentChangedAt":"2026-08-11T17:42:36.556Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}