Cargo "lock file needs to be updated but --frozen" in CI

CI built with --frozen (or --locked), which forbids modifying Cargo.lock. But Cargo.toml changed in a way the committed lock file does not reflect, so cargo refuses rather than silently updating the lock.

What this error means

cargo aborts with error: the lock file <path>/Cargo.lock needs to be updated but --frozen was passed to prevent this. It is deterministic until the lock file is regenerated and committed.

cargo

error: the lock file /home/runner/work/app/Cargo.lock needs to be updated but --frozen was passed to prevent this
If you want to try to generate the lock file without accessing the network, remove the --frozen flag and use --offline instead.

Common causes

Cargo.toml changed without updating the lock

A dependency was added, removed, or version-bumped in Cargo.toml but Cargo.lock was not regenerated and committed, so the two disagree under --frozen.

Lock file not committed

For binaries the Cargo.lock should be checked in; a missing or stale lock fails the frozen build.

How to fix it

Regenerate and commit Cargo.lock

Update the lock locally to match Cargo.toml, then commit it.

Terminal

cargo update --workspace --offline 2>/dev/null || cargo generate-lockfile
git add Cargo.lock
git commit -m "Update Cargo.lock"

Add a lock-check step to CI

Fail early and clearly when the lock drifts.

.github/workflows/ci.yml

cargo metadata --format-version 1 --locked >/dev/null

How to prevent it

Commit Cargo.lock for binaries and keep it in sync with Cargo.toml.
Run a --locked check in CI so drift fails fast in PRs.
Regenerate the lock whenever you edit dependency versions.