{"record":{"id":"f4de21ec8b8bc3d2","repo":"BoundaryML/baml","slug":"kind-toolchain-artifact-fingerprint-format-artifact-format","errorCode":null,"errorMessage":"{kind}: toolchain {artifact_fingerprint} / format {artifact_format}; this runtime: {runtime_fingerprint} / format {runtime_format} — {remediation}","messagePattern":"(.+?): toolchain (.+?) / format (.+?); this runtime: (.+?) / format (.+?) — (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"baml_language/crates/baml_artifact/src/lib.rs","lineNumber":133,"sourceCode":"#[derive(Debug, thiserror::Error)]\npub enum Error {\n    #[error(\"{kind} artifact is truncated\")]\n    Truncated { kind: ArtifactKind },\n    #[error(\n        \"{kind} is not a versioned BAML artifact; {}\",\n        kind.remediation()\n    )]\n    InvalidMagic { kind: ArtifactKind },\n    #[error(\"invalid {kind} artifact header: {message}\")]\n    InvalidHeader { kind: ArtifactKind, message: String },\n    #[error(\"expected {expected} artifact, found {actual}\")]\n    WrongKind {\n        expected: ArtifactKind,\n        actual: ArtifactKind,\n    },\n    #[error(\"{kind} artifact failed integrity validation\")]\n    InvalidPayloadHash { kind: ArtifactKind },\n    #[error(\n        \"{kind}: toolchain {artifact_fingerprint} / format {artifact_format}; this runtime: {runtime_fingerprint} / format {runtime_format} — {remediation}\"\n    )]\n    Incompatible {\n        kind: ArtifactKind,\n        artifact_fingerprint: String,\n        artifact_format: u32,\n        runtime_fingerprint: &'static str,\n        runtime_format: u32,\n        remediation: &'static str,\n    },\n    #[error(\"failed to encode {kind}: {message}\")]\n    Encode { kind: ArtifactKind, message: String },\n    #[error(\"failed to decode {kind}: {message}\")]\n    Decode { kind: ArtifactKind, message: String },\n}\n\n/// Serialize `value` and wrap it in a versioned artifact envelope.\npub fn encode<T: BorshSerialize>(kind: ArtifactKind, value: &T) -> Result<Vec<u8>, Error> {","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/baml_language/crates/baml_artifact/src/lib.rs#L115-L151","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Regenerate the artifacts with the toolchain version matching the runtime (follow the message's remediation hint).","Pin identical BAML CLI and runtime versions in your lockfile/CI to keep fingerprints in sync.","Re-run code generation as part of your build whenever either the toolchain or runtime is upgraded.","If you must keep the old artifact, downgrade the runtime to the version that produced it."],"exampleFix":"// before\nbaml generate  # with baml-cli 0.10 while runtime is 0.12\n// after\nnpm install @baml/cli@0.12 && baml generate  # versions aligned, then regenerate","handlingStrategy":"validation","validationCode":"if (manifest.fingerprint !== runtimeFingerprint || manifest.formatVersion !== RUNTIME_FORMAT) {\n  throw new Error('artifact/toolchain incompatible with this runtime — run baml generate');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin BAML CLI and runtime to the same version in lockfiles and CI.","Run code generation automatically whenever versions change.","Never commit stale generated artifacts alongside upgraded runtimes."],"tags":["artifact","version-mismatch","compatibility","code-generation"],"backgroundTag":"incompatible-source-type","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}