rust-lang/cargo · error

lock file version ` ` requires `-Znext-lockfile-bump

Error message

lock file version `{current_version:?}` requires `-Znext-lockfile-bump`

What it means

Thrown when the lockfile's version is greater than `ResolveVersion::max_stable()` (i.e. it uses an unstable, future lockfile format) and the `-Znext-lockfile-bump` unstable feature flag is not enabled. This prevents older Cargo versions or unflagged builds from silently consuming an experimental lockfile format.

Solutions

1. Enable the feature: `cargo build -Znext-lockfile-bump` (requires nightly Cargo).
2. Downgrade the lockfile by deleting it and running `cargo generate-lockfile` with a stable Cargo.
3. Pin all collaborators to the same Cargo version to avoid format mismatches.

Example fix

# Option 1: enable the unstable flag (nightly required)
cargo +nightly build -Znext-lockfile-bump

# Option 2: regenerate with stable Cargo
rm Cargo.lock
cargo generate-lockfile

// Check Cargo.lock version before building
use std::path::Path;
fn check_lockfile_version_compat(lockfile: &Path) -> Result<(), String> {
    let content = std::fs::read_to_string(lockfile).map_err(|e| e.to_string())?;
    if let Some(line) = content.lines().find(|l| l.starts_with("version = ")) {
        let v: u32 = line.trim_start_matches("version = ").trim().parse().unwrap_or(1);
        if v > 3 { // max_stable as of writing
            return Err(format!("lockfile version {} requires -Znext-lockfile-bump; delete Cargo.lock and regenerate or enable the flag", v));
        }
    }
    Ok(())
}

When it happens

Trigger: Opening or building a project whose `Cargo.lock` has a `version` field ahead of the current stable maximum (e.g. version 4 when only 3 is stable), without `-Znext-lockfile-bump` in `CARGO_UNSTABLE_NEXT_LOCKFILE_BUMP` or the `-Z` flag.

Common situations: Checking out a repository where a newer or nightly Cargo wrote a next-version lockfile; downgrading Cargo after a nightly wrote the lockfile; collaborating across Cargo versions where one uses experimental lockfile features.

Related errors

• not implemented
• parsing ` ` requires `-Zscript
• parsing ` ` requires `-Zscript
• a Cargo.lock must exist for this command
• artifact-dir was not locked during clean

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

Appendix: source

Thrown at src/ops/lockfile.rs:86

        );
    }

    // 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);
        out = serialize_resolve(resolve, orig.as_deref());
    } else if current_version > ResolveVersion::max_stable() && !next_lockfile_bump {
        // The next version hasn't yet stabilized.
        anyhow::bail!("lock file version `{current_version:?}` requires `-Znext-lockfile-bump`")
    }

    if !lock_root.as_path_unlocked().exists() {
        lock_root.create_dir()?;
    }

    // Ok, if that didn't work just write it out
    lock_root
        .open_rw_exclusive_create(LOCKFILE_NAME, ws.gctx(), "Cargo.lock file")
        .and_then(|mut f| {
            f.file().set_len(0)?;
            f.write_all(out.as_bytes())?;
            Ok(())
        })
        .with_context(|| {
            format!(
                "failed to write {}",
                lock_root.as_path_unlocked().join(LOCKFILE_NAME).display()

View on GitHub (pinned to eb98b54bc9)