cargo 'failed to verify the checksum of X' - how to fix

TL;DR

The downloaded crate bytes do not match the hash in Cargo.lock. Clear the cached download and fetch again; a corrupt cache is the common cause. If the mismatch persists across machines, treat it as a supply-chain signal and investigate before overriding anything.

Error

cargo 'failed to verify the checksum of X'  -  how to fix

Steps

1. Remove the cached download: delete the crate file for X from the registry cache under the cargo home, then run cargo fetch. Expected output: cargo downloads a fresh copy of the crate.

2. Rebuild: cargo build. Expected output: The checksum verifies and the build proceeds.

3. If it still fails, check whether the version was yanked and republished; compare with a second machine or a fresh container. Expected output: You learn whether the corruption is local or the published bytes changed.

4. If the bytes genuinely changed upstream, do not hand-edit the checksum in Cargo.lock; instead move to a version whose published checksum verifies. Expected output: The lockfile records a trustworthy hash.

5. Report a republished-with-different-bytes crate to the registry; that should not happen silently. Expected output: The incident is tracked, not just worked around.

When to use

• cargo fails with failed to verify the checksum of X
• The error shows expected versus actual hashes for a registry crate
• A fresh clone on another machine builds fine; the local cache is suspect

When not to use

• cargo cannot find the package at all; that is resolution, not integrity
• The failure is failed to load source; fix the fetch first
• You are using a vendored source; verify the vendor dir instead of the cache

Variant phrasings

Checksum mismatch for a crate after cargo update

The update shape; the new version's download corrupted in transit or in cache.

failed to verify the checksum on CI but not locally

Points at a poisoned CI cache; clear the cargo cache on the runner.

Crate bytes changed after a yank and republish

Rare and serious; move versions and report it rather than editing the lockfile hash.

Why it happens

Cargo.lock records a hash of the exact crate file the registry served. Anything that alters the bytes in transit or in the local cache (a truncated download, disk corruption, a bad proxy) fails verification. The check exists to catch exactly this, including the serious case of a crate republished with different bytes.

Edge cases

• Never "fix" this by copying the actual hash into Cargo.lock; that blesses whatever bytes you downloaded.
• Proxies that recompress or scan downloads are a classic cause; verify against a direct download.
• --offline builds use only the cache, so a poisoned cache fails deterministically until cleared.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_mnyY7-3JQbA5EbveSzZ4gA