rust-lang/cargo · error · anyhow::Error

failed to verify the checksum of `{}`

Error message

failed to verify the checksum of `{}`

What it means

After Cargo downloads a `.crate` tarball from a remote registry it recomputes the SHA-256 of the bytes and compares against the `checksum` recorded in the registry index (`download::finish_download`, src/sources/registry/download.rs:100). A mismatch means the downloaded content does not match the registry's recorded hash, so Cargo refuses to persist or unpack it.

Source

Thrown at src/sources/registry/download.rs:102

    })
}

/// Verifies the integrity of `data` with `checksum` and persists it under the
/// directory at `cache_path`.
///
/// This is primarily called by [`RegistryData::finish_download`](super::RegistryData::finish_download).
pub(super) fn finish_download(
    cache_path: &Filesystem,
    gctx: &GlobalContext,
    encoded_registry_name: InternedString,
    pkg: PackageId,
    checksum: &str,
    data: &[u8],
) -> CargoResult<File> {
    // Verify what we just downloaded
    let actual = Sha256::new().update(data).finish_hex();
    if actual != checksum {
        anyhow::bail!("failed to verify the checksum of `{}`", pkg)
    }
    gctx.deferred_global_last_use()?.mark_registry_crate_used(
        global_cache_tracker::RegistryCrate {
            encoded_registry_name,
            crate_filename: pkg.tarball_name().into(),
            size: data.len() as u64,
        },
    );

    cache_path.create_dir()?;
    let path = cache_path.join(&pkg.tarball_name());
    let path = gctx.assert_package_cache_locked(CacheLockMode::DownloadExclusive, &path);
    let mut dst = OpenOptions::new()
        .create(true)
        .read(true)
        .write(true)
        .open(&path)
        .with_context(|| format!("failed to open `{}`", path.display()))?;

View on GitHub (pinned to 0e07a15537)

Solutions

1. Delete the cached tarball under `~/.cargo/registry/cache/` for that registry and re-run `cargo fetch` to re-download.
2. Clear the whole registry cache (`cargo cache -a` or `rm -rf ~/.cargo/registry/cache/*`) and retry on a stable connection.
3. If using a mirror, verify the mirror's index and crate storage are in sync; switch `source` replacement back to crates.io to confirm.
4. Check for disk space / filesystem errors and for any intercepting proxy (set `CARGO_HTTP_CHECK_REVOKE=false` or adjust `http.proxy`) if the transport is being altered.

Example fix

# before: repeated checksum failures from a bad cached blob
cargo build

# after: evict the bad download and refetch
rm -rf ~/.cargo/registry/cache/index.crates.io-*/<pkg>-<ver>.crate
cargo fetch

# Before relying on a downloaded crate, evict suspect caches.
# (shell, run before cargo if checksum errors recur)
find ~/.cargo/registry/cache -name '<pkg>-<ver>.crate' -delete

When it happens

Trigger: Corrupted/truncated download (network drop, flaky proxy, disk write error); a tampered or MITM-altered tarball; a registry mirror serving a stale/mismatched `.crate` for the indexed checksum; concurrent writers corrupting the partial file (though Cargo uses exclusive locks to mitigate).

Common situations: Flaky CI network behind a corporate proxy caching a bad copy; a misconfigured registry mirror whose index and crate blobs are out of sync; disk-full / filesystem corruption during write; CDN serving a partially decompressed gzip.

Related errors

• failed to verify the checksum of `{}`
• config.json not found
• invalid tarball downloaded, contains a file at {entry_path:?
• invalid tarball downloaded, contains an entry at {entry_path
• remote registries must have config

AI-assisted analysis of rust-lang/cargo@0e07a15537 (2026-08-06). Data as JSON: /data/errors/8f8e92b95703d662.json. Report an issue: GitHub.