What causes "expected {expected} artifact, found {actual}" in BoundaryML/baml?

Point the consumer at the artifact file whose kind matches what it expects (check the generator's output paths).

BoundaryML/baml · error · Error

expected {expected} artifact, found {actual}

Error message

expected {expected} artifact, found {actual}

What it means

`Error::WrongKind` is returned when an artifact is a valid versioned BAML artifact, but of a different `ArtifactKind` than the one requested by the decoder. For example, passing a client-library artifact where a runtime manifest artifact is expected.

Source

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

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,
    },
    #[error("failed to encode {kind}: {message}")]

View on GitHub (pinned to bd85ce9dee)

Solutions

Point the consumer at the artifact file whose kind matches what it expects (check the generator's output paths).
Regenerate all artifacts so every consumer finds its matching kind.
Fix build configuration (output dirs / file names) so each artifact kind is written where the runtime reads it.

Defensive patterns

Strategy: validation

Validate before calling

const actual = readArtifactKind(path);
if (actual !== expectedKind) {
  throw new Error(`wrong artifact at ${path}: expected ${expectedKind}, found ${actual}`);
}

Prevention

Wire each consumer to the exact artifact output path for its kind.
Regenerate all artifact kinds together after build-config changes.
Name artifact files by kind to prevent mix-ups.

When it happens

Trigger: Calling the artifact decode/validate API with an `expected` kind that does not match the `actual` kind stored in the envelope; loading the wrong generated file into a consumer that expects a specific artifact type.

Common situations: Wiring the wrong output path in the build pipeline (e.g., feeding the generated client where the IR manifest goes); stale config pointing at an old artifact slot; a renamed or reordered artifact output directory.

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

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