BoundaryML/baml · error · Error

failed to encode {kind}: {message}

Error message

failed to encode {kind}: {message}

What it means

`Error::Encode` wraps a Borsh serialization failure that occurred while encoding a value into an artifact envelope. The inner `message` is the underlying borsh error. This happens on the producer side, when a value cannot be serialized into bytes at all.

Source

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

    #[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> {
    let payload = borsh::to_vec(value).map_err(|error| Error::Encode {
        kind,
        message: error.to_string(),
    })?;
    encode_payload(kind, &payload)
}

/// Encode a value with an explicit artifact format for cross-crate skew tests.
#[cfg(feature = "test-support")]
#[doc(hidden)]
pub fn encode_with_format_for_test<T: BorshSerialize>(

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Read the inner `message` to identify the field/type that failed to serialize.
2. Fix the BorshSerialize implementation (or the offending data type) for the failing field.
3. Ensure the payload type is plain data (no unserializable constructs) and bounded in size.
4. Update the baml_artifact/borsh dependency versions so serialization impls are consistent.

Example fix

// before
struct Manifest { children: Rc<Vec<Node>> }  // Rc not Borsh-friendly
// after
struct Manifest { children: Vec<Node> }  // plain owned data serializes cleanly

// Rust
match baml_artifact::encode(ArtifactKind::Ir, &value) {
    Ok(bytes) => write_artifact(bytes),
    Err(baml_artifact::Error::Encode { message, .. }) => {
        eprintln!("artifact encode failed: {message} — check BorshSerialize impls");
    }
    Err(e) => return Err(e.into()),
}

When it happens

Trigger: Calling the crate's `encode::<T: BorshSerialize>(kind, value)` (baml_artifact/src/lib.rs:150) with a type whose Borsh serialization fails — e.g., data containing structures Borsh cannot handle or a custom Serialize impl that errors.

Common situations: A newly added field type in the IR/client payload lacks a correct BorshSerialize impl; extremely large or cyclic data structures; a custom type changed its serialization semantics and now fails mid-encode.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

• failed to decode {kind}: {message}
• {kind} artifact is truncated
• invalid {kind} artifact header: {message}
• invalid package interface: {message}
• variant `{}` requires an explicit discriminant to stabilize

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