Cargo "failed to verify the checksum" of a Crate in CI

By Kaveh Alemi·Latchkey

Cargo downloaded a crate but its hash did not match the checksum recorded in Cargo.lock or the index. Almost always a corrupted or truncated download, or a stale cached .crate file - not tampering.

What this error means

cargo fails with failed to verify the checksum of <crate> during fetch or build. It often follows a flaky download or a restored cache, and clearing the cached crate and re-fetching usually clears it - the mark of a transient corruption.

error: failed to verify the checksum of `syn v2.0.48`

Caused by:
  checksum for `syn v2.0.48` changed between lock files

# or
error: checksum for `syn v2.0.48` does not match the checksum in the index

Common causes

Corrupted or truncated download

A download interrupted mid-transfer leaves a partial or corrupt .crate file in the cache. Its hash no longer matches, and verification fails.

Stale or poisoned registry cache

A CI cache restored a ~/.cargo/registry whose cached crate or index entry no longer matches the checksum in the current Cargo.lock.

How to fix it

Clear the cached crate and re-fetch

Remove the corrupted cache entries so Cargo downloads a clean copy and re-verifies.

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

Invalidate a stale CI cache

Bump the cache key so a poisoned registry cache is rebuilt from a clean fetch.

- uses: actions/cache@v4
  with:
    path: ~/.cargo/registry
    key: cargo-v2-${{ hashFiles('Cargo.lock') }}

How to prevent it

• Cache ~/.cargo/registry keyed on Cargo.lock so it tracks the resolved set.
• Set CARGO_NET_RETRY so partial downloads retry instead of caching corruption.
• Resolve Cargo.lock merge conflicts by regenerating, not hand-editing checksums.

Frequently asked questions

Related guides

References

• The Cargo Book
• GitHub Actions documentation