BoundaryML/baml · error · VmPanic

baml.panics.IntegerOverflow

baml.panics.IntegerOverflow

Error message

integer overflow: {message}

What it means

This panic is raised when an arithmetic operation on a BAML `int` (i63) produces a result outside the representable range [INT_MIN, INT_MAX]. It carries a human-readable description of the operation (e.g. "4611686018427387903 + 1"). It is built only on the cold overflow path, so the String allocation never touches the hot arithmetic code path.

Source

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

    BinOp, CmpOp, SysOpErrorCategory, UnaryOp, Value,
    types::{ObjectType, Type},
};

/// A catchable BAML panic — maps 1:1 to a `baml.panics.*` class.
///
/// These are user-visible runtime errors (division by zero, index out of
/// bounds, etc.) that can be caught by `catch` handlers. The handler's
/// `ThrowIfPanic` instruction filters which panics are caught vs rethrown.
#[derive(Debug, Error, PartialEq, Clone)]
pub enum VmPanic {
    #[error("division by zero: {left:?} / {right:?}")]
    DivisionByZero { left: Value, right: Value },

    /// An `int` (i63) arithmetic operation overflowed the representable
    /// range `[INT_MIN, INT_MAX]`. Carries a human-readable description of
    /// the operation (e.g. `"4611686018427387903 + 1"`); built only on the
    /// cold overflow path, so the `String` alloc never touches hot code.
    #[error("integer overflow: {message}")]
    IntegerOverflow { message: String },

    // 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,

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Clamp or bounds-check operands before arithmetic to keep results within [INT_MIN, INT_MAX].
2. Catch the panic in BAML via `baml.panics.IntegerOverflow` if overflow is an expected case in your algorithm.
3. If wider range is needed, restructure the computation (e.g. reduce early, use logarithms) or move big-integer math to the host language.

Example fix

// before
let total = 0;
for (i in huge_list) { total = total + i * i; }
// after
let total = 0;
for (i in huge_list) {
  if (total > INT_MAX - i * i) { return INT_MAX; }
  total = total + i * i;
}

// BAML: bounds-check before arithmetic
if (a > 0 && b > INT_MAX - a) { return err("addition would overflow"); }

// BAML helper
fn fits_i63(v: int) -> bool { return v >= INT_MIN && v <= INT_MAX; }

// BAML
try {
  let r = a + b;
} catch (e: baml.panics.IntegerOverflow) {
  return err("overflow: " + e.message);
}

When it happens

Trigger: Any `int` arithmetic that exceeds the i63 range: adding, subtracting, or multiplying large values, negating INT_MIN, or a sequence of increments like INT_MAX + 1. The message names the exact operation that overflowed.

Common situations: Loop accumulators that keep growing (e.g. factorial or power computations), converting huge counters or bit math without bounds checks, users assuming 64-bit int semantics when BAML ints are i63.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• baml.panics.DivisionByZero
• baml.panics.IndexOutOfBounds
• baml.panics.InvalidFieldAccess
• baml.panics.MapKeyNotFound
• baml.panics.StackOverflow

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