BoundaryML/baml · error

instanceof requires a class instance on the left side at

Error message

instanceof requires a class instance on the left side at {:?}

What it means

The BAML interpreter's `instanceof` operator only works when the left-hand operand evaluates to a class instance (a Class value). This error is thrown when the left side is any other value type (int, string, list, null, etc.). It is a runtime type check inside expression evaluation.

Solutions

1. Ensure the left operand is a value constructed as a class instance (e.g. via a class constructor) before using instanceof
2. Check for null/undefined values first; instanceof on a possibly-null value throws
3. Use a different type check (equality, field access) for primitives instead of instanceof
4. Inspect the expression metadata position printed in the message to find the offending operand

Example fix

// before
if (maybeUser instanceof User) { ... }   // maybeUser is null or a string
// after
if (maybeUser != null && maybeUser instanceof User) { ... }

// before: x instanceof ClassName
// guard that x is a class instance at all
if (x == null) { throw new Error("left side of instanceof is null"); }

function isClassInstance(v) { return v != null && typeof v === 'object' && v.__baml_class != null; }

try { evalExpr(expr); } catch (e) { if (String(e).includes('instanceof requires a class instance')) { /* treat as non-instance */ } else { throw e; } }

When it happens

Trigger: Evaluating an `x instanceof ClassName` expression where `x` holds a non-class value: a primitive, a list, a map, null, or an unevaluated variable holding those.

Common situations: Checking a value that came from an LLM response or a function return that the developer assumed was a class instance but is actually null (e.g. failed/partial parse) or a raw primitive; typo'd variable shadowing so the left side is a scalar instead of the constructed object.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• expected value, found function
• push() can only be called on arrays at
• division by zero at
• division by zero in /= operator
• for loop requires iterable (list)

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

Appendix: source

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

                        )
                        .await?,
                    )?;

                    // Extract class name from right side (should be Expr::Var)
                    let class_name = match right.as_ref() {
                        Expr::Var(name, _) => name.clone(),
                        _ => bail!(
                            "instanceof requires a class name on the right side at {:?}",
                            meta.0
                        ),
                    };

                    // Check if left value is a class instance matching the class name
                    let result = match left_val {
                        BamlValueWithMeta::Class(ref left_class, ..) => {
                            BamlValueWithMeta::Bool(left_class == &class_name, meta.clone())
                        }
                        _ => bail!(
                            "instanceof requires a class instance on the left side at {:?}",
                            meta.0
                        ),
                    };

                    EvalValue::Value(result)
                } else {
                    // Normal binary operation: evaluate both sides
                    let left_val = expect_value(
                        evaluate_expr(
                            left,
                            scopes,
                            thir,
                            run_llm_function,
                            watch_handler,
                            function_name,
                        )
                        .await?,

View on GitHub (pinned to bd85ce9dee)