nikivdev/code · critical

checksum mismatch for {}

Error message

checksum mismatch for {}

What it means

install verifies downloaded binaries against the sha256 recorded in the registry manifest, unless --no-verify is passed. If the computed hash of the downloaded bytes differs from the expected hash for that binary, install aborts with 'checksum mismatch for <bin>' to protect against corrupted or tampered downloads.

Source

Thrown at src/registry.rs:249

    let path = target_entry
        .binaries
        .get(&bin)
        .with_context(|| format!("No binary '{}' in manifest", bin))?;
    let download_url = resolve_download_url(&registry_url, path);
    let response = client
        .get(download_url)
        .send()
        .context("failed to download binary")?;
    if !response.status().is_success() {
        bail!("download failed ({})", response.status());
    }
    let bytes = response.bytes().context("failed to read download")?;

    if !opts.no_verify {
        if let Some(expected) = target_entry.sha256.get(&bin) {
            let actual = sha256_bytes(&bytes);
            if expected != &actual {
                bail!("checksum mismatch for {}", bin);
            }
        }
    }

    let bin_dir = opts.bin_dir.clone().unwrap_or_else(default_bin_dir);
    fs::create_dir_all(&bin_dir)
        .with_context(|| format!("failed to create {}", bin_dir.display()))?;
    let dest = bin_dir.join(&bin);
    if dest.exists() && !opts.force {
        bail!(
            "{} already exists (use --force to overwrite)",
            dest.display()
        );
    }

    let mut temp = NamedTempFile::new_in(&bin_dir)
        .with_context(|| format!("failed to create temp file in {}", bin_dir.display()))?;
    temp.write_all(&bytes)?;

View on GitHub (pinned to a747e741ae)

Solutions

1. Retry the download — transient corruption is the most common cause.
2. Do NOT blindly use --no-verify; first re-publish the package so the manifest hash matches the binary if the publisher changed artifacts.
3. Check for proxy/CDN interference and clear caches.
4. If mismatch persists, treat the artifact as untrusted and alert the package publisher.

Example fix

// before (dangerous workaround)
mytool install --name mypkg --no-verify

// after
mytool install --name mypkg   # let sha256 verification run; republish if hashes are stale

// Verify checksum yourself before trusting the artifact (mirror of the library check)
let actual = sha256_bytes(&bytes);
let expected = target_entry.sha256.get(&bin)
    .ok_or("no expected checksum recorded")?;
if expected != &actual {
    return Err("downloaded artifact does not match manifest checksum; refusing to install".into());
}

match install(opts) {
    Err(e) if e.to_string().contains("checksum mismatch") => {
        eprintln!("Artifact integrity check failed: retry once; if it persists, republish the package or investigate tampering. Do NOT use --no-verify.");
        std::process::exit(1);
    }
    other => other,
}

When it happens

Trigger: sha256_bytes(downloaded bytes) != target_entry.sha256[bin] during install (with verification enabled). Happens when the stored binary differs from the manifest hash.

Common situations: Partial/corrupted download through a proxy; registry manifest republished with binaries from a different build; man-in-the-middle tampering; a CDN serving a stale cached artifact.

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• checksum mismatch for {} (expected {}, got {})
• checksums.txt does not contain {}. Refusing to install. Set
• Relative path must not contain '..'.
• Refusing to commit sensitive files. Set FLOW_ALLOW_SENSITIVE
• Refusing to commit potential secrets. Review the findings ab

AI-assisted analysis of nikivdev/code@a747e741ae (2026-09-01). Data as JSON: /api/errors/93d8dddb8114049e. Report an issue: GitHub.