cannot the lock file because was passed to prevent…

Error message

cannot {action} the lock file {lockfile_path} because {locked_flag} was passed to prevent this
help: to generate the lock file without accessing the network, remove the {locked_flag} flag and use --offline instead.

What it means

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.

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.

Example fix

# Before — fails because lockfile is stale
cargo build --locked

# After — update lockfile first, then use --locked
cargo update
git add Cargo.lock && git commit -m "update lockfile"
cargo build --locked

Defensive patterns

Strategy: validation

Validate before calling

use std::path::Path;
fn lockfile_is_fresh(ws_root: &Path) -> Result<(), String> {
    let lockfile = ws_root.join("Cargo.lock");
    if !lockfile.is_file() {
        return Err("Cargo.lock missing; run `cargo generate-lockfile` before using --locked".into());
    }
    // Optionally run cargo metadata to check if lockfile matches manifest
    Ok(())
}

Prevention

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`.

When it happens

Trigger: 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`.

Common situations: 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.

Related errors

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

Appendix: source

Thrown at src/ops/lockfile.rs:64

    let (orig, mut out, lock_root) = resolve_to_string_orig(ws, resolve);

    // If the lock file contents haven't changed so don't rewrite it. This is
    // helpful on read-only filesystems.
    if let Some(orig) = &orig {
        if are_equal_lockfiles(orig, &out, ws) {
            return Ok(false);
        }
    }

    if let Some(locked_flag) = ws.gctx().locked_flag() {
        let lockfile_path = lock_root.as_path_unlocked().join(LOCKFILE_NAME);
        let action = if lockfile_path.exists() {
            "update"
        } else {
            "create"
        };
        let lockfile_path = lockfile_path.display();
        anyhow::bail!(
            "cannot {action} the lock file {lockfile_path} because {locked_flag} was passed to prevent this\n\
             help: to generate the lock file without accessing the network, \
             remove the {locked_flag} flag and use --offline instead."
        );
    }

    // While we're updating the lock file anyway go ahead and update its
    // encoding to whatever the latest default is. That way we can slowly roll
    // out lock file updates as they're otherwise already updated, and changes
    // which don't touch dependencies won't seemingly spuriously update the lock
    // file.
    let default_version = ResolveVersion::with_rust_version(ws.lowest_rust_version());
    let current_version = resolve.version();
    let next_lockfile_bump = ws.gctx().cli_unstable().next_lockfile_bump;
    tracing::debug!("lockfile - current: {current_version:?}, default: {default_version:?}");

    if current_version < default_version {
        resolve.set_version(default_version);

View on GitHub (pinned to eb98b54bc9)