BoundaryML/baml · critical · FetchError

sha256 mismatch for {url}: expected {expected}, got {got}

Error message

sha256 mismatch for {url}: expected {expected}, got {got}

What it means

FetchError::ChecksumMismatch is thrown by baml_release when the sha256 of the downloaded artifact does not match the checksum recorded in the release manifest. This is a security/integrity guard against corrupted or tampered downloads; the error reports the URL, expected hash, and actual hash.

Source

Thrown at baml_language/crates/baml_release/src/lib.rs:91

    }
}

#[derive(Debug, thiserror::Error)]
pub enum FetchError {
    #[error("network error fetching {url}: {source}")]
    Network { url: String, source: reqwest::Error },
    #[error("HTTP {status} fetching {url}")]
    HttpStatus {
        url: String,
        status: reqwest::StatusCode,
    },
    #[error("manifest 404 for version {version} (not released yet?)")]
    ManifestNotFound { version: String },
    #[error("manifest schema {got} not supported (max {max}); run `baml self-update`")]
    ManifestSchemaTooNew { got: u32, max: u32 },
    #[error("target {target} not built for version {version}")]
    TargetNotInManifest { target: String, version: String },
    #[error("sha256 mismatch for {url}: expected {expected}, got {got}")]
    ChecksumMismatch {
        url: String,
        expected: String,
        got: String,
    },
    #[error("archive missing expected binary {name}")]
    BinaryNotInArchive { name: String },
    #[error("archive contains unsafe path {path}")]
    UnsafeArchivePath { path: String },
    #[error("disk error: {0}")]
    Io(#[from] std::io::Error),
    #[error("zip archive error: {0}")]
    Zip(#[from] zip::result::ZipError),
}

#[derive(Debug, Clone)]
pub struct Fetcher {
    pub spec: ReleaseSpec,

View on GitHub (pinned to bd85ce9dee)

Solutions

  1. Retry the download to rule out transient corruption
  2. Clear any download/proxy cache and retry via a direct connection
  3. Compare the expected/got hashes; if persistent, verify the artifact on the release server
  4. Check whether a mirror or proxy is modifying the response (bypass HTTPS_PROXY)
  5. Report the mismatch if the official artifact genuinely disagrees with its manifest

Example fix

# before (cached corrupt artifact kept being reused)
$ baml self-update
sha256 mismatch for https://releases.baml.com/.../cli.zip: expected ab12..., got ff00...
# after
$ rm -rf ~/.cache/baml/downloads
$ baml self-update
Defensive patterns

Strategy: retry

Validate before calling

// verify checksum yourself before installing
let sum = sha256_hex(download(&url)?);
if sum != manifest.checksum {
    eprintln!("pre-check failed: expected {} got {}", manifest.checksum, sum);
}

Type guard

fn is_checksum_err(e: &FetchError) -> bool {
    matches!(e, FetchError::ChecksumMismatch { .. })
}

Try / catch

match install(v) {
    Err(FetchError::ChecksumMismatch { url, expected, got }) => {
        warn!("corrupt download from {url}; purging cache and retrying");
        purge_download_cache();
        retry_once_or_fail()
    }
    other => other,
}

Prevention

When it happens

Trigger: Downloading a release archive whose computed sha256 differs from the manifest — interrupted/corrupted downloads, proxies rewriting content, or a mismatch between the manifest and the actually published artifact.

Common situations: Flaky corporate proxies or TLS-intercepting middleboxes altering the payload, partially cached downloads on a bad CDN node, manually edited manifest/artifacts, or installing through a custom mirror with stale artifacts.

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

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