BoundaryML/baml · error · Error

invalid {kind} artifact header: {message}

Error message

invalid {kind} artifact header: {message}

What it means

`Error::InvalidHeader` is raised when the artifact's magic is present but a header field fails validation — e.g., a malformed version, length, hash, or kind field — with a free-form `message` describing the exact problem. It indicates a structurally broken versioned envelope.

Source

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

#[derive(Debug, Clone, PartialEq, Eq, BorshSerialize, BorshDeserialize)]
struct ArtifactHeader {
    build_fingerprint: String,
    kind: ArtifactKind,
    payload_len: u64,
    payload_hash: Hash,
}

#[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,

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Regenerate the artifact with the BAML toolchain rather than repairing it by hand.
2. Re-download the artifact and verify its checksum against the publisher's manifest.
3. Check the `message` field for the specific invalid header field and fix the producing pipeline accordingly.
4. Ensure no post-processing step (minifier, packer, text-mode transfer) is rewriting the binary artifact.

if (artifactBytes.length < HEADER_MIN_LEN) {
  throw new Error('artifact too small to contain a valid header; regenerate');
}

When it happens

Trigger: Decoding an artifact whose header fields are corrupt or nonsensical (bad lengths, unknown header version, mismatched kind marker) via the artifact decode path.

Common situations: Bit rot or partial corruption on disk; hand-edited or post-processed artifact files; a bug in a custom producer writing the envelope; mixing headers/fragments from two different artifacts.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• {kind} artifact is truncated
• {kind} artifact failed integrity validation
• failed to encode {kind}: {message}
• failed to decode {kind}: {message}
• {kind} is not a versioned BAML artifact; {}

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