{"record":{"id":"d9748e890b50f2a8","repo":"BoundaryML/baml","slug":"kind-is-not-a-versioned-baml-artifact","errorCode":null,"errorMessage":"{kind} is not a versioned BAML artifact; {}","messagePattern":"(.+?) is not a versioned BAML artifact; (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"baml_language/crates/baml_artifact/src/lib.rs","lineNumber":119,"sourceCode":"        formatter.write_str(self.label())\n    }\n}\n\npub type Hash = [u8; 32];\n\n#[derive(Debug, Clone, PartialEq, Eq, BorshSerialize, BorshDeserialize)]\nstruct ArtifactHeader {\n    build_fingerprint: String,\n    kind: ArtifactKind,\n    payload_len: u64,\n    payload_hash: Hash,\n}\n\n#[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,","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/baml_language/crates/baml_artifact/src/lib.rs#L101-L137","documentation":"`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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Regenerate the artifact with the matching BAML toolchain version (follow the remediation hint in the message).","Confirm you are passing the generated artifact file, not the source or a different file.","Align runtime and CLI versions (upgrade the runtime or pin the toolchain) so both use the same artifact envelope version.","Re-download the artifact if the file may have been corrupted in transit."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const fd = fs.openSync(path, 'r');\nconst magic = Buffer.alloc(4);\nfs.readSync(fd, magic, 0, 4, 0);\nfs.closeSync(fd);\nif (!magic.equals(BAML_ARTIFACT_MAGIC)) {\n  throw new Error('not a BAML artifact — regenerate with the matching toolchain');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only feed generated artifact files to the runtime, never source files.","Regenerate artifacts after every toolchain upgrade.","Keep runtime and CLI versions pinned together."],"tags":["artifact","magic-number","version-mismatch","format"],"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"}