BoundaryML/baml · error · Error

{kind} is not a versioned BAML artifact; {}

Error message

{kind} is not a versioned BAML artifact; {}

What it means

`Error::InvalidMagic` means the byte stream does not start with the expected versioned BAML artifact magic number, so it is not an artifact this runtime can parse. The thiserror message appends `ArtifactKind::remediation()` telling the user what to do (typically rebuild with a compatible toolchain).

Source

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

        formatter.write_str(self.label())
    }
}

pub type Hash = [u8; 32];

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

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Regenerate the artifact with the matching BAML toolchain version (follow the remediation hint in the message).
2. Confirm you are passing the generated artifact file, not the source or a different file.
3. Align runtime and CLI versions (upgrade the runtime or pin the toolchain) so both use the same artifact envelope version.
4. Re-download the artifact if the file may have been corrupted in transit.

const fd = fs.openSync(path, 'r');
const magic = Buffer.alloc(4);
fs.readSync(fd, magic, 0, 4, 0);
fs.closeSync(fd);
if (!magic.equals(BAML_ARTIFACT_MAGIC)) {
  throw new Error('not a BAML artifact — regenerate with the matching toolchain');
}

When it happens

Trigger: Decoding a file that was never produced by the BAML artifact encoder; loading a legacy or third-party file into the artifact reader; reading a file whose first bytes were corrupted or misaligned.

Common situations: Pointing the runtime at a source `.baml` file or plain binary instead of the generated artifact; a toolchain upgrade changed the envelope format; an out-of-date runtime reading artifacts from a newer generator.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• {kind}: toolchain {artifact_fingerprint} / format {artifact_
• {kind} artifact is truncated
• invalid {kind} artifact header: {message}
• expected {expected} artifact, found {actual}
• {kind} artifact failed integrity validation

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