cargo "checksum for X did not match" (lock vs index) in CI

By Daniel Zoghalchali·Latchkey

cargo downloaded a crate (or read its index entry) and the SHA-256 did not match the checksum stored in Cargo.lock. The lockfile is stale relative to the index, a mirror served a different artifact, or the download was corrupted.

What this error means

cargo build fails with "error: checksum for X vN changed between lock files" or "checksum for X vN did not match what is in the lockfile", aborting before the crate is used.

error: checksum for `serde v1.0.203` changed between lock files

this could be indicative of a few possible errors:
    * the lock file is corrupt
    * a replacement source in use (e.g. a mirror) returned a different checksum
    * the source itself may be corrupt in some way

Common causes

A stale lockfile after an index or mirror change

The lockfile records a checksum that no longer matches what the configured index or mirror now serves for that version.

A mirror serving a different artifact

A source replacement or registry mirror returned a crate whose hash differs from the upstream the lock was generated against.

How to fix it

Regenerate the lockfile against the real source

1. Remove the offending entry so cargo recomputes it: cargo update -p X.
2. Confirm the same index/mirror is used locally and in CI.
3. Commit the refreshed Cargo.lock.

cargo update -p serde
cargo build --locked

Re-fetch on a corrupted download

Clear the cached crate so a clean copy is fetched; if the mismatch persists for the same file from the real index, the lock is stale, not the download.

rm -rf ~/.cargo/registry/cache
cargo fetch --locked

How to prevent it

• Use one consistent index/mirror across local and CI.
• Regenerate the lockfile when you change registries or mirrors.
• Review Cargo.lock checksum diffs in code review.

Frequently asked questions

Related guides

References

• The Cargo Book
• GitHub Actions documentation