Fix it fast
Most likely: A manifest or environment input changed without a reviewed lockfile update.
Confirm this is your error
Match the output and confirm you are troubleshooting the same failure.
error: the lock file Cargo.lock needs to be updated but --locked was passed to prevent this
error: the lock file /workspace/Cargo.lock needs to be updated but --locked was passed to prevent thisCheck the cause
Run focused checks to identify what is failing in this environment.
cargo -Vv
git status --short -- Cargo.toml Cargo.lock
git diff -- Cargo.toml Cargo.lockApply the safe fix
Use the smallest safe change that addresses the confirmed cause.
# On a controlled branch with the pinned toolchain
cargo check
git diff -- Cargo.lockVerify it works
Repeat the relevant checks and confirm the original error is gone.
cargo check --locked
git diff --exit-code -- Cargo.lockAvoid unsafe shortcuts
Keep security and data protections in place while troubleshooting.
- Do not remove
--lockedfrom CI merely to make the job pass. - Do not commit a regenerated lockfile without reviewing the package and source changes.
What Broke in the Dependency Graph
This is Cargo refusing to continue with a dependency graph that does not make sense. The important detail is which versions or peer requirements disagree, not just the final error code.
Repair the dependency graph
Try to repair the version graph instead of forcing past it. A successful command with mismatched dependencies is usually just a slower failure later.
Legitimate manifest change:regenerate Cargo.lock with the pinned project toolchain, review the diff, run tests, and commit both files together.
Missing checkout file:restore the reviewed lockfile to the CI context instead of disabling --locked
Toolchain skew:pin the same Rust toolchain locally and in CI before regenerating the lockfile.
Unexpected source change:restore the prior registry or source-replacement config, or deliberately re-resolve against the new source and review every changed package.
Offline container:prefetch dependencies for the same lockfile and targets before the locked build stage.
Why Resolution Broke
A dependency was added or changed in Cargo.toml without committing the corresponding lockfile update.
The repository expects a lockfile, but it is missing from the checkout or excluded by packaging or source-control rules.
Local and CI Cargo versions or resolver defaults produce different lockfile requirements.
A registry, source replacement, target, or workspace input changed and now produces a different resolution.
Prove the Graph Is Clean Again
Re-run the original command with --locked in the same runner or container. Cargo should proceed without writing Cargo.lock.
Run git diff --exit-code -- Cargo.lock after verification to prove the strict build did not mutate dependency state.
Find why Cargo wants to change the lockfile
Run cargo -Vv in the failing runner and compare it with the toolchain used when the lockfile was last generated.
Confirm that Cargo.lock exists in the checkout and inspect git status --short -- Cargo.toml Cargo.lock for uncommitted manifest or lockfile changes.
Compare workspace manifests, target-specific dependencies, feature flags, and source configuration with the last successful CI revision.
On a disposable branch, run the command without --locked and inspect the resulting Cargo.lock diff. Treat this as a state-changing diagnostic, not the final fix.
What --locked protects
This is the part worth understanding if the quick fix did not hold. It explains what Cargo is trying to do at the moment the error appears.
--locked requires the existing Cargo.lock to remain sufficient and unchanged. Cargo exits when the file is missing or when current manifest and resolver inputs require another graph.
This is especially useful in CI because it exposes uncommitted lockfile changes, toolchain skew, source changes, and build steps that accidentally resolve dependencies differently.
Keep the Dependency Graph Healthy
To prevent this, require manifest and lockfile changes in the same pull request for applications and other lockfile-committing projects, pin the Rust toolchain used by developers, release automation, and CI, and keep --locked in deterministic CI jobs and make lockfile regeneration a separate reviewed workflow.
Docs and source code
Cargo Dependency Resolution
Official explanation of version selection, lockfiles, yanked releases, features, and resolver conflicts. - Source
This process is called dependency resolution and is performed by the resolver.cargo fetch
Official prefetch workflow for later offline or locked builds. - Source
Fetch dependencies of a package from the network.