BoundaryML/baml · critical

SHA256 checksum verification failed. Expected: {}, Actual: {

Error message

SHA256 checksum verification failed. Expected: {}, Actual: {}

What it means

verify_sha256_checksum computes SHA-256 of the downloaded asset bytes and compares to the expected checksum from the checksum file. On mismatch it errors with both hashes, refusing to extract a potentially corrupt or tampered archive.

Source

Thrown at engine/playground-server/src/server.rs:284

    }

    let checksum_text = checksum_resp.text().await?;

    // Parse the expected checksum (format: "hash filename" or just "hash")
    let expected_checksum = checksum_text
        .split_whitespace()
        .next()
        .ok_or_else(|| anyhow::anyhow!("Invalid checksum file format"))?
        .to_lowercase();

    // Calculate actual checksum
    let mut hasher = Sha256::new();
    hasher.update(file_bytes);
    let actual_checksum = format!("{:x}", hasher.finalize());

    // Verify checksums match
    if actual_checksum != expected_checksum {
        return Err(anyhow::anyhow!(
            "SHA256 checksum verification failed. Expected: {}, Actual: {}",
            expected_checksum,
            actual_checksum
        ));
    }

    tracing::info!("SHA256 checksum verification passed");
    Ok(())
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Re-download (delete the partial cache under ~/.baml/playground and retry) — transient corruption is most common.
2. Compare the logged Expected/Actual hashes with `sha256sum` of a manually downloaded asset to identify which side is stale.
3. If the release was re-uploaded, regenerate and republish the checksum file; otherwise check for a transparent proxy altering the payload.

sha256sum downloaded-asset.tar.gz | awk '{print $1}'  # compare with published value before install

match get_playground_dist().await {
    Err(e) if e.to_string().contains("SHA256 checksum verification failed") => {
        purge_cache("~/.baml/playground");
        retry_once_or_alert();
    }
    r => r?,
}

When it happens

Trigger: actual_checksum != expected_checksum after hashing file_bytes — the downloaded archive bytes differ from what the published checksum describes.

Common situations: Interrupted/corrupted download (truncated archive); CDN serving a stale or different asset for the same URL; proxy injecting content (HTML error pages); asset re-uploaded without updating the checksum file; case mismatch handled via to_lowercase, so usually genuine byte differences.

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

• blob size mismatch for {}; expected {} bytes, got {} bytes
• blob digest mismatch for {}; computed {}
• Checksum mismatch: expected {expected}, got {actual}
• {kind} artifact failed integrity validation
• sha256 mismatch for {url}: expected {expected}, got {got}

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/7bfd2cf76b0427d9. Report an issue: GitHub.