{"record":{"id":"8f8e92b95703d662","repo":"rust-lang/cargo","slug":"failed-to-verify-the-checksum-of","errorCode":null,"errorMessage":"failed to verify the checksum of `{}`","messagePattern":"failed to verify the checksum of `(.+?)`","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/sources/registry/download.rs","lineNumber":102,"sourceCode":"    })\n}\n\n/// Verifies the integrity of `data` with `checksum` and persists it under the\n/// directory at `cache_path`.\n///\n/// This is primarily called by [`RegistryData::finish_download`](super::RegistryData::finish_download).\npub(super) fn finish_download(\n    cache_path: &Filesystem,\n    gctx: &GlobalContext,\n    encoded_registry_name: InternedString,\n    pkg: PackageId,\n    checksum: &str,\n    data: &[u8],\n) -> CargoResult<File> {\n    // Verify what we just downloaded\n    let actual = Sha256::new().update(data).finish_hex();\n    if actual != checksum {\n        anyhow::bail!(\"failed to verify the checksum of `{}`\", pkg)\n    }\n    gctx.deferred_global_last_use()?.mark_registry_crate_used(\n        global_cache_tracker::RegistryCrate {\n            encoded_registry_name,\n            crate_filename: pkg.tarball_name().into(),\n            size: data.len() as u64,\n        },\n    );\n\n    cache_path.create_dir()?;\n    let path = cache_path.join(&pkg.tarball_name());\n    let path = gctx.assert_package_cache_locked(CacheLockMode::DownloadExclusive, &path);\n    let mut dst = OpenOptions::new()\n        .create(true)\n        .read(true)\n        .write(true)\n        .open(&path)\n        .with_context(|| format!(\"failed to open `{}`\", path.display()))?;","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/rust-lang/cargo/blob/eb98b54bc9f3c74519f43d066cb3fd02ebc88df0/src/sources/registry/download.rs#L84-L120","documentation":"After downloading a `.crate` tarball from a registry, Cargo computes `SHA256(data)` and compares it to the checksum recorded in the registry index / lockfile. A mismatch means the downloaded bytes differ from what the registry attests — indicating corruption, a man-in-the-middle, a stale mirror, or a tampered cache. The error names the package id that failed.","triggerScenarios":"`finish_download` in `src/sources/registry/download.rs` is called after the HTTP fetch completes; the computed SHA-256 of `data` does not equal the `checksum` argument passed in. Triggered by truncated downloads, proxy corruption, disk errors, registry mirror skew, or an out-of-date index pointing at a replaced tarball.","commonSituations":"Flaky network/proxy truncating the tarball; a corporate mirror whose cached `.crate` was replaced but whose index was not updated; concurrent processes writing into `~/.cargo/registry/cache`; disk/full-filesystem partial writes; clock-skewed or partially-synced registry mirrors.","solutions":["Clear the cached tarball: `cargo cache --autoclean` or remove `~/.cargo/registry/cache/<index>/<pkg>-<ver>.crate`, then re-run.","Re-fetch the index: `rm -rf ~/.cargo/registry/index/<index>` and `cargo fetch`, to rule out a stale index.","Switch off or update the registry mirror/proxy that may be serving a mismatched tarball.","Verify network integrity (retry on a stable connection, disable aggressive VPN/proxy caching)."],"exampleFix":"# before: download corrupted/mismatched\n$ cargo build\nerror: failed to verify the checksum of `serde v1.0.0`\n\n# after: clear and refetch\n$ rm -rf ~/.cargo/registry/cache/index.crates.io-*/serde-1.0.0.crate\n$ cargo fetch && cargo build","handlingStrategy":"retry","validationCode":"// Before trusting a downloaded tarball, recompute and compare.\nfn verify_crate_sha256(path: &Path, expected: &str) -> Result<(), anyhow::Error> {\n    let data = std::fs::read(path)?;\n    use sha2::{Digest, Sha256};\n    let mut h = Sha256::new(); h.update(&data);\n    let got = hex::encode(h.finalize());\n    if got != expected { anyhow::bail!(\"checksum mismatch for {}: got {}\", path.display(), got); }\n    Ok(())\n}","typeGuard":"fn checksum_matches(path: &std::path::Path, expected: &str) -> bool {\n    std::fs::read(path).ok().map(|d| {\n        use sha2::{Digest, Sha256}; let mut h = Sha256::new(); h.update(&d);\n        hex::encode(h.finalize()) == expected\n    }).unwrap_or(false)\n}","tryCatchPattern":"for attempt in 0..3 {\n    match registry.finish_download(...) {\n        Ok(f) => return Ok(f),\n        Err(e) if e.to_string().contains(\"checksum\") && attempt < 2 => {\n            let _ = std::fs::remove_file(&crate_path); // retry after clearing\n            continue;\n        }\n        Err(e) => return Err(e),\n    }\n}","preventionTips":["Keep `~/.cargo/registry/cache` on reliable storage.","Use trustworthy registries / mirrors with consistent index+crate state.","In CI, cache the registry but verify checksums on restore.","Avoid interrupting Cargo mid-download."],"tags":["cargo","registry","checksum","sha256","download","integrity"],"backgroundTag":null,"analyzedSha":"eb98b54bc9f3c74519f43d066cb3fd02ebc88df0","analyzedAt":"2026-08-11T17:42:36.556Z","contentChangedAt":"2026-08-11T17:42:36.556Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}