Cargo "lock file needs to be updated" with --locked in CI

By Daniel Zoghalchali·Latchkey

Cargo detected that Cargo.toml was edited but Cargo.lock was not regenerated to match. With --locked or --frozen in CI, Cargo refuses to silently change the lockfile and fails instead.

What this error means

A cargo build --locked or cargo test --frozen step fails immediately with "the lock file ... needs to be updated but --locked was passed to prevent this". It appears right after someone changes a dependency without re-running cargo locally.

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

Diagnose it: toolchain, features, or a stale target dir?

Cargo failures that only appear in CI are usually a different toolchain channel, a different feature set resolved by the dependency graph, or a target directory restored from a cache built with different flags.

rustc --version --verbose
cargo --version
cat rust-toolchain.toml 2>/dev/null

# which features actually got enabled across the graph?
cargo tree -e features | head -40

# rule out a poisoned cache before anything else
cargo clean && cargo build --locked

Common causes

Dependencies edited without re-locking

A change to Cargo.toml (added, removed, or bumped dependency) was committed without regenerating Cargo.lock, so the two disagree and --locked rejects the mismatch.

Cargo.lock not committed

If Cargo.lock is gitignored or never committed for a binary crate, CI cannot reproduce the resolved set and the locked build fails.

How to fix it

Regenerate and commit the lockfile

Run cargo locally so it reconciles Cargo.lock with Cargo.toml, then commit the result.

cargo generate-lockfile   # or any cargo build
git add Cargo.lock && git commit -m "Update Cargo.lock"

Verify the lock is current in CI

Fail fast if a PR changes dependencies but forgets to re-lock.

cargo update --locked --workspace   # errors if Cargo.lock is stale

How to prevent it

• Commit Cargo.lock for binaries and run cargo build --locked in CI.
• Run a cargo command locally after editing Cargo.toml so the lock updates.
• Add a lock-freshness check step to catch drift in PRs.

Frequently asked questions

Related guides

References

• The Cargo Book
• GitHub Actions documentation