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

> Fix cargo "the lock file needs to be updated but --locked was passed" in CI - Cargo.toml changed without regenerating Cargo.lock under --locked/--frozen.

Source: https://latchkey.dev/learn/rust/cargo-lock-out-of-date-locked  
Updated: 2026-06-25

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.

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

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

> Always build with `--locked` in CI. Without it Cargo may update `Cargo.lock` silently, so CI tests a dependency set that is not the one you committed.

## FAQ

### What causes Cargo "lock file needs to be updated" with --locked in CI?

There are 2 common causes: dependencies edited without re-locking and cargo.lock not committed. 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.

### How do I fix Cargo "lock file needs to be updated" with --locked in CI?

There are 2 fixes depending on which cause you have: regenerate and commit the lockfile and verify the lock is current in ci. Work through them in order, since the first is the most common.

### What does Cargo "lock file needs to be updated" with --locked in CI actually mean?

A cargo build --locked or cargo test --frozen step fails immediately with "the lock file ...

### How do I stop Cargo "lock file needs to be updated" with --locked in CI happening again?

Commit Cargo.lock for binaries and run cargo build --locked in CI. The prevention section lists 3 changes that keep it from recurring.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt