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

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