BoundaryML/baml · critical · BamlSysError

Checksum mismatch: expected {expected}, got {actual}

Error message

Checksum mismatch: expected {expected}, got {actual}

What it means

After downloading the BAML native library, baml-sys hashes the downloaded file and compares it against the expected checksum; this error fires when they differ, indicating a corrupted, truncated, or tampered download. The library refuses to use the file to protect against running altered native code. The message shows both the expected and actual digests.

Source

Thrown at languages/rust/baml-sys/src/error.rs:49

    VersionMismatch { expected: String, actual: String },

    /// Platform not supported.
    #[error("Platform not supported: {os}/{arch}")]
    UnsupportedPlatform {
        os: &'static str,
        arch: &'static str,
    },

    /// Failed to determine cache directory.
    #[error("Failed to determine cache directory: {0}")]
    CacheDir(String),

    /// Download failed.
    #[error("Failed to download library: {0}")]
    DownloadFailed(String),

    /// Checksum mismatch after download.
    #[error("Checksum mismatch: expected {expected}, got {actual}")]
    ChecksumMismatch { expected: String, actual: String },

    /// IO error.
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    /// Library already initialized with different path.
    #[error("Library already initialized from {existing_path}, cannot change to {requested_path}")]
    AlreadyInitialized {
        existing_path: PathBuf,
        requested_path: PathBuf,
    },
}

/// Result type for baml-sys operations.
pub type Result<T> = std::result::Result<T, BamlSysError>;

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Delete the cached/downloaded file and retry the download (usually a transient corruption)
2. Clear the whole baml cache directory to force a clean re-download
3. Check for a proxy or mirror intercepting and altering the download
4. Verify you are not mixing BAML client versions with mismatched pinned checksums
5. Manually verify the artifact hash against the official published checksum

Example fix

// before
# corrupted cache reused
// after
rm -rf ~/.cache/baml && rerun

match baml_sys::init() {
    Err(BamlSysError::ChecksumMismatch { expected, actual }) => {
        eprintln!("corrupt download (expected {expected}, got {actual}); clearing cache");
        clear_baml_cache();
        // one clean retry
    }
    other => other.map(|_| ())?,
}

When it happens

Trigger: Downloading the library when the transfer is truncated or corrupted, a caching proxy serves a stale/partial file, an artifact was replaced on the server while the client expects a pinned checksum, or the local cache write was corrupted.

Common situations: Flaky CI networks producing partial downloads, transparent HTTP proxies mangling binaries, version upgrades where the client's expected checksum no longer matches a re-published artifact, or disk corruption in the cache directory.

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

• sha256 mismatch for {url}: expected {expected}, got {got}
• ErrChecksumMismatch
• Failed to download checksum file: {e}
• SHA256 checksum verification failed. Expected: {}, Actual: {
• Failed to download library: {0}

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