{"record":{"id":"a089e7ddd7ccdb85","repo":"rust-lang/cargo","slug":"cannot-action-the-lock-file-lockfile-path-beca","errorCode":null,"errorMessage":"cannot {action} the lock file {lockfile_path} because {locked_flag} was passed to prevent this\nhelp: to generate the lock file without accessing the network, remove the {locked_flag} flag and use --offline instead.","messagePattern":"cannot (.+?) the lock file (.+?) because (.+?) was passed to prevent this\nhelp: to generate the lock file without accessing the network, remove the (.+?) flag and use --offline instead\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/ops/lockfile.rs","lineNumber":64,"sourceCode":"    let (orig, mut out, lock_root) = resolve_to_string_orig(ws, resolve);\n\n    // If the lock file contents haven't changed so don't rewrite it. This is\n    // helpful on read-only filesystems.\n    if let Some(orig) = &orig {\n        if are_equal_lockfiles(orig, &out, ws) {\n            return Ok(false);\n        }\n    }\n\n    if let Some(locked_flag) = ws.gctx().locked_flag() {\n        let lockfile_path = lock_root.as_path_unlocked().join(LOCKFILE_NAME);\n        let action = if lockfile_path.exists() {\n            \"update\"\n        } else {\n            \"create\"\n        };\n        let lockfile_path = lockfile_path.display();\n        anyhow::bail!(\n            \"cannot {action} the lock file {lockfile_path} because {locked_flag} was passed to prevent this\\n\\\n             help: to generate the lock file without accessing the network, \\\n             remove the {locked_flag} flag and use --offline instead.\"\n        );\n    }\n\n    // While we're updating the lock file anyway go ahead and update its\n    // encoding to whatever the latest default is. That way we can slowly roll\n    // out lock file updates as they're otherwise already updated, and changes\n    // which don't touch dependencies won't seemingly spuriously update the lock\n    // file.\n    let default_version = ResolveVersion::with_rust_version(ws.lowest_rust_version());\n    let current_version = resolve.version();\n    let next_lockfile_bump = ws.gctx().cli_unstable().next_lockfile_bump;\n    tracing::debug!(\"lockfile - current: {current_version:?}, default: {default_version:?}\");\n\n    if current_version < default_version {\n        resolve.set_version(default_version);","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/rust-lang/cargo/blob/eb98b54bc9f3c74519f43d066cb3fd02ebc88df0/src/ops/lockfile.rs#L46-L82","documentation":"Thrown when writing the lockfile would require creating or updating it, but `--locked` or `--frozen` was passed. These flags instruct Cargo to refuse any lockfile mutation. The error identifies the flag (`--locked` or `--frozen`), the action (`create` or `update`), and the lockfile path, and suggests `--offline` as an alternative for network-free operation.","triggerScenarios":"Running any Cargo command with `--locked` or `--frozen` when the lockfile is out of date or missing and needs to be regenerated. The check fires in `write_pkg_lockfile` when `locked_flag()` returns `Some`.","commonSituations":"CI pipelines using `--frozen` where dependencies changed but the lockfile wasn't committed; `--locked` in a Dockerfile where the lockfile is stale; adding a new dependency without updating Cargo.lock.","solutions":["Run `cargo update` or `cargo generate-lockfile` (without `--locked`/`--frozen`) to refresh the lockfile, then commit it.","If network access is the concern, use `--offline` instead of `--locked`/`--frozen`.","Ensure `Cargo.lock` is committed to the repository and kept up to date."],"exampleFix":"# Before — fails because lockfile is stale\ncargo build --locked\n\n# After — update lockfile first, then use --locked\ncargo update\ngit add Cargo.lock && git commit -m \"update lockfile\"\ncargo build --locked","handlingStrategy":"validation","validationCode":"use std::path::Path;\nfn lockfile_is_fresh(ws_root: &Path) -> Result<(), String> {\n    let lockfile = ws_root.join(\"Cargo.lock\");\n    if !lockfile.is_file() {\n        return Err(\"Cargo.lock missing; run `cargo generate-lockfile` before using --locked\".into());\n    }\n    // Optionally run cargo metadata to check if lockfile matches manifest\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always commit Cargo.lock for applications and binaries.","Run `cargo update` after changing dependencies, then commit the lockfile.","In CI, generate the lockfile in a step before using `--locked` or `--frozen`."],"tags":["lockfile","locked","frozen","ci","flag-conflict"],"backgroundTag":null,"analyzedSha":"eb98b54bc9f3c74519f43d066cb3fd02ebc88df0","analyzedAt":"2026-08-11T17:42:36.556Z","contentChangedAt":"2026-08-11T17:42:36.556Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}