What causes "assertion failed" in BoundaryML/baml?

Inspect the assert's condition and the actual runtime values (log the operands just before the assert) to find why it failed.

BoundaryML/baml · error

assertion failed

Error message

assertion failed

What it means

Raised when a BAML `assert` statement's condition evaluates to false at runtime. The interpreter evaluates the assert's expression, and if the result is Bool(false) it aborts execution with "assertion failed". This is intentional runtime verification: the BAML program's own invariant was violated during evaluation of the expression block.

Source

Thrown at engine/baml-compiler/src/thir/interpret.rs:1286

                                }
                            }
                        }
                    }
                    Statement::Assert { condition, .. } => {
                        let cond_val = expect_value(
                            evaluate_expr(
                                condition,
                                scopes,
                                thir,
                                run_llm_function,
                                watch_handler,
                                function_name,
                            )
                            .await?,
                        )?;
                        match cond_val {
                            BamlValueWithMeta::Bool(true, _) => {}
                            BamlValueWithMeta::Bool(false, _) => bail!("assertion failed"),
                            _ => bail!("assert condition must be boolean"),
                        }
                    }
                    Statement::WatchOptions {
                        variable,
                        channel,
                        when,
                        span,
                    } => {
                        // Find and update the watch variable for this variable
                        // We need to find the watch variable by checking which one references the same value
                        for scope in scopes.iter_mut().rev() {
                            if let Some(var_ref) = scope.variables.get(variable) {
                                // Find the watch variable that references this variable
                                if let Some(watch_var) = scope
                                    .watch_variables
                                    .iter_mut()
                                    .find(|wv| Arc::ptr_eq(&wv.value_ref, var_ref))

View on GitHub (pinned to bd85ce9dee)

Solutions

Inspect the assert's condition and the actual runtime values (log the operands just before the assert) to find why it failed.
Add input validation before the asserted region so bad data fails with a clearer message.
Relax or correct the assert if the invariant was too strict, using an if/else to return an error value instead.
Guard against non-deterministic LLM output with retries or fallbacks before the assert.

Example fix

// before (BAML)
assert len(answer) > 0;
// after
if (len(answer) == 0) {
  "default answer"
} else {
  answer
}

Defensive patterns

Strategy: try-catch

Try / catch

try {
  const result = await bamlFn(ctx, args);
  return result;
} catch (e) {
  if (String(e).includes("assertion failed")) {
    // fall back to a safe path or retry with a stricter prompt
    return fallbackValue;
  }
  throw e;
}

Prevention

Validate inputs before the asserted region so failures have clear causes.
Log/assert operands separately to pinpoint which sub-condition fails.
Don't assert on unvalidated LLM output; retry or fall back first.
Use asserts for true invariants only; return error values for recoverable cases.

When it happens

Trigger: Executing a BAML expression block containing `assert <cond>;` where <cond> evaluates to false — e.g. `assert x > 0;` with x <= 0, or asserting on LLM output that failed an expected property.

Common situations: Validating LLM responses in BAML functions (asserting a field is non-empty, a number in range); inputs that don't satisfy preconditions; upstream model behavior changed and no longer satisfies the asserted invariant.

Related errors

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