What causes "assertion failed" in BoundaryML/baml?

Inspect the failing condition and validate inputs before reaching the assertion.

BoundaryML/baml · error · VmPanic

baml.panics.AssertionFailed

baml.panics.AssertionFailed

Error message

assertion failed

What it means

Raised when a VM assertion instruction fails, i.e. a runtime check inserted into the BAML program evaluated to false. It carries no payload; the surrounding program is expected to provide context. It surfaces user-authored or compiler-inserted invariant checks.

Source

Thrown at baml_language/crates/bex_vm_types/src/errors.rs:51

    // Raised by array and byte-array subscripting, so the message stays generic
    // ("index", not "array index").
    #[error("index out of bounds: {index} of {length}")]
    IndexOutOfBounds { index: i64, length: usize },

    #[error("invalid field access: field {field_index} of {field_count}")]
    InvalidFieldAccess {
        field_index: usize,
        field_count: usize,
    },

    #[error("key not found in map")]
    MapKeyNotFound,

    #[error("stack overflow")]
    StackOverflow,

    #[error("assertion failed")]
    AssertionFailed,

    #[error("unreachable code executed")]
    Unreachable,

    #[error("operation cancelled")]
    Cancelled,

    /// A user-caused panic from `baml.sys.panic`, and the stdlib's panic of
    /// record for a user-violated native invariant (e.g. a reflection kind
    /// view's `_ty` field overwritten with a type of a different kind).
    #[error("baml.sys.panic: {message}")]
    UserPanic { message: String },

    /// A clean process-termination request from `baml.sys.exit(code)`.
    ///
    /// Catchable in user code as `baml.panics.Exit` — patterned after
    /// Python's `SystemExit`: code can intercept it for cleanup or

View on GitHub (pinned to bd85ce9dee)

Solutions

Inspect the failing condition and validate inputs before reaching the assertion.
Replace the bare assert with an explicit check that returns a descriptive error to the caller.
Catch `baml.panics.AssertionFailed` at the boundary only if you cannot fix the condition upstream.

Example fix

// before
assert(items.length > 0);
// after
if (items.length == 0) { return err("items must be non-empty"); }

Defensive patterns

Strategy: try-catch

Validate before calling

// BAML: validate the precondition instead of asserting it
if (items.length == 0) { return err("items must be non-empty"); }

Try / catch

// BAML
try {
  run_checked(input);
} catch (e: baml.panics.AssertionFailed) {
  return err("assertion violated for input " + describe(input));
}

Prevention

Turn assertions on external input into explicit error returns
Re-audit assertions after refactors that change invariants
Keep assertions for internal invariants only, not user data

When it happens

Trigger: Executing an `assert` (or compiler-generated assertion) whose condition is false at runtime, e.g. `assert(x > 0)` where x is 0 or negative.

Common situations: Assertions validating preconditions on user input, invariants after transformations (e.g. sortedness, non-emptiness), regressions after refactoring where an assumption no longer holds.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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