BoundaryML/baml · error · Error

{kind} artifact failed integrity validation

Error message

{kind} artifact failed integrity validation

What it means

`Error::InvalidPayloadHash` means the artifact's declared payload hash does not match the hash of the bytes actually present, so the payload has been altered or corrupted since encoding. This is the crate's integrity check protecting against tampered or damaged artifacts.

Source

Thrown at baml_language/crates/baml_artifact/src/lib.rs:131

}

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("{kind} artifact is truncated")]
    Truncated { kind: ArtifactKind },
    #[error(
        "{kind} is not a versioned BAML artifact; {}",
        kind.remediation()
    )]
    InvalidMagic { kind: ArtifactKind },
    #[error("invalid {kind} artifact header: {message}")]
    InvalidHeader { kind: ArtifactKind, message: String },
    #[error("expected {expected} artifact, found {actual}")]
    WrongKind {
        expected: ArtifactKind,
        actual: ArtifactKind,
    },
    #[error("{kind} artifact failed integrity validation")]
    InvalidPayloadHash { kind: ArtifactKind },
    #[error(
        "{kind}: toolchain {artifact_fingerprint} / format {artifact_format}; this runtime: {runtime_fingerprint} / format {runtime_format} — {remediation}"
    )]
    Incompatible {
        kind: ArtifactKind,
        artifact_fingerprint: String,
        artifact_format: u32,
        runtime_fingerprint: &'static str,
        runtime_format: u32,
        remediation: &'static str,
    },
    #[error("failed to encode {kind}: {message}")]
    Encode { kind: ArtifactKind, message: String },
    #[error("failed to decode {kind}: {message}")]
    Decode { kind: ArtifactKind, message: String },
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Regenerate or re-download the artifact from a trusted source.
2. Verify the artifact checksum against the publisher's manifest before decoding.
3. Stop any process that rewrites the artifact after it is produced; transfer in binary mode only.
4. Check storage health (disk errors, flaky mounts) if corruption recurs.

const hash = crypto.createHash('sha256').update(fs.readFileSync(path)).digest('hex');
if (hash !== manifest.artifacts['ir'].sha256) {
  throw new Error('artifact integrity check failed; re-download');
}

When it happens

Trigger: Decoding an artifact whose payload bytes differ from the hash recorded in the header — bit flips on disk, in-flight corruption, or post-encoding modification of the payload region.

Common situations: Faulty storage or flaky network corrupting the artifact file; a tool that rewrites the file after generation; syncing artifacts with tools that mangle binary content (line-ending conversion, encoding transcoding).

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

• {kind} artifact is truncated
• invalid {kind} artifact header: {message}
• blob size mismatch for {}; expected {} bytes, got {} bytes
• blob digest mismatch for {}; computed {}
• profiling usage ledger checksum mismatch

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