BoundaryML/baml · error · Error

{kind} artifact is truncated

Error message

{kind} artifact is truncated

What it means

`Error::Truncated` in baml_artifact indicates that the artifact blob ended before the header and payload declared by the versioned envelope. The reader parsed the length fields but the buffer ran out of bytes, so the artifact cannot be trusted or deserialized.

Source

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

impl fmt::Display for ArtifactKind {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        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}"
    )]

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Regenerate or re-download the artifact — the file is unrecoverable.
2. Verify the artifact file size matches what the producing toolchain reported (checksum/size manifest).
3. Re-run the build step that emits the artifact, ensuring writes are flushed and atomic (write to temp then rename).
4. Check disk space and filesystem health on the machine that stored the artifact.

const stat = fs.statSync(artifactPath);
const expected = manifest.artifacts['ir'].sizeBytes;
if (stat.size !== expected) {
  throw new Error(`artifact truncated: ${stat.size} of ${expected} bytes; re-download`);
}

When it happens

Trigger: Decoding an artifact (via the crate's decode path) whose byte buffer is shorter than its declared header+payload length; passing a partially-written or clipped file to the artifact decoder.

Common situations: A download was interrupted leaving a partial artifact file; a build/packaging step wrote the file but crashed before flushing; copying artifacts with tools that truncate (e.g., interrupted scp/rsync); reading a file while a concurrent writer still has it open.

Understand the failure class

Background: "Invalid JSON response" and "Failed to parse response" errors: when an API answers 200 but the body isn't the JSON your library expected — this error's family across 28 libraries.

Related errors

• invalid {kind} artifact header: {message}
• {kind} artifact failed integrity validation
• failed to encode {kind}: {message}
• failed to decode {kind}: {message}
• {kind} is not a versioned BAML artifact; {}

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