BoundaryML/baml · error · Error

{kind}: toolchain {artifact_fingerprint} / format {artifact_

Error message

{kind}: toolchain {artifact_fingerprint} / format {artifact_format}; this runtime: {runtime_fingerprint} / format {runtime_format} — {remediation}

What it means

`Error::Incompatible` reports a fingerprint/format mismatch between the artifact and the current runtime: the artifact was produced by toolchain fingerprint `artifact_fingerprint` with format version `artifact_format`, while this runtime expects `runtime_fingerprint`/`runtime_format`. A `remediation` hint tells the user how to realign them. This is the version-compatibility gate of the artifact envelope.

Source

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

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

/// Serialize `value` and wrap it in a versioned artifact envelope.
pub fn encode<T: BorshSerialize>(kind: ArtifactKind, value: &T) -> Result<Vec<u8>, Error> {

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Regenerate the artifacts with the toolchain version matching the runtime (follow the message's remediation hint).
2. Pin identical BAML CLI and runtime versions in your lockfile/CI to keep fingerprints in sync.
3. Re-run code generation as part of your build whenever either the toolchain or runtime is upgraded.
4. If you must keep the old artifact, downgrade the runtime to the version that produced it.

Example fix

// before
baml generate  # with baml-cli 0.10 while runtime is 0.12
// after
npm install @baml/cli@0.12 && baml generate  # versions aligned, then regenerate

if (manifest.fingerprint !== runtimeFingerprint || manifest.formatVersion !== RUNTIME_FORMAT) {
  throw new Error('artifact/toolchain incompatible with this runtime — run baml generate');
}

When it happens

Trigger: Decoding an artifact generated by a different BAML toolchain version than the runtime embedding baml_artifact; upgrading one side (CLI or runtime package) without regenerating artifacts.

Common situations: After `npm/pip install` of a newer BAML runtime while generated artifacts on disk are stale; pinning different BAML versions across team members or CI; mixing generated code checked into the repo with an upgraded toolchain.

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} is not a versioned BAML artifact; {}
• Update to @boundaryml/baml required. Version from generators
• {kind} artifact is truncated
• invalid {kind} artifact header: {message}
• expected {expected} artifact, found {actual}

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