cargo: 'the lock file Cargo.lock needs to be updated but --locked was passed' in CI

TL;DR

Cargo.toml and Cargo.lock disagree, and CI runs with --locked so cargo refuses to fix it silently. Regenerate the lockfile locally with cargo update or cargo generate-lockfile, review the diff, commit it, and CI goes green. Keep --locked in CI; it is the guardrail doing its job.

Error

cargo: 'the lock file Cargo.lock needs to be updated but --locked was passed' in CI

Steps

1. Reproduce locally: cargo build --locked (or cargo check --locked). Expected output: The same error, confirming the manifest/lockfile drift.

2. Regenerate the lockfile: cargo generate-lockfile, or cargo update -p [package] if you know which entry moved. Expected output: Cargo.lock is rewritten to match Cargo.toml.

3. Review the diff: git diff Cargo.lock, checking the version moves are the ones you expect. Expected output: The diff is scoped to the intended change.

4. Commit Cargo.lock alongside the Cargo.toml change. Expected output: The repo carries a consistent pair.

5. Confirm CI: the --locked build passes. Expected output: Deterministic CI builds from the committed lockfile.

When to use

• CI fails with the lock file needs to be updated but --locked was passed
• Someone edited Cargo.toml and forgot to update Cargo.lock
• A merge changed Cargo.toml on both sides without a lockfile refresh

When not to use

• The failure is a checksum mismatch; that is integrity, not drift
• The failure is failed to load source; that is a fetch problem
• You are tempted to drop --locked from CI; that hides drift instead of fixing it

Variant phrasings

cargo build --locked fails after editing Cargo.toml

The local shape; generate-lockfile reconciles the two files.

--locked failure after merging dependency changes

Merge the manifests, regenerate the lockfile once, commit.

Agent edited Cargo.toml and CI broke on --locked

Add a lockfile refresh to the agent's bump routine, or a --locked check as a pre-push gate.

Why it happens

--locked tells cargo the lockfile is authoritative: if Cargo.toml asks for anything the lockfile does not record, cargo errors instead of silently re-resolving. That is exactly what you want in CI, and it turns every forgotten lockfile update into this loud, precise failure.

Edge cases

• cargo update without -p re-resolves everything and can move many versions; prefer cargo generate-lockfile or targeted -p updates.
• Workspaces share one root Cargo.lock; edits in any member manifest can trigger it.
• If the Cargo.toml edit was a mistake, revert it rather than re-locking around it.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_c7SFmrp563ccS9O2NXmJbQ