BoundaryML/baml · error · EngineError

Type mismatch: {message}

Error message

Type mismatch: {message}

What it means

A generic type-mismatch failure at the engine boundary, with a human-readable message describing which types disagreed. Thrown when an operation receives a value of one BAML type where another was required and no coercion applies.

Source

Thrown at baml_language/crates/bex_engine/src/lib.rs:845

    /// Either a BAML panic or a BAML error value.
    #[error("{}", format_unhandled_throw(value, trace))]
    UnhandledThrow {
        value: Box<BexExternalValue>,
        trace: Vec<bex_vm::StackFrame>,
    },

    /// Clean process-termination request from `baml.sys.exit(code)`.
    /// The caller is expected to honor this as the process exit code.
    /// BAML `int` is `i64`, so the signal carries the full value; the
    /// caller clamps into its shell's range (typically 0..=255 on Unix).
    #[error("baml.sys.exit({code})")]
    Exit { code: i64 },

    #[error("Cannot convert object of type {type_name}")]
    CannotConvert { type_name: String },

    #[error("Type mismatch: {message}")]
    TypeMismatch { message: String },

    #[error("Schema inconsistency: {message}")]
    SchemaInconsistency { message: String },

    #[cfg(feature = "heap_debug")]
    #[error("Snapshot not possible for type: {type_name}")]
    CannotSnapshot { type_name: String },

    #[error("A function call with ID {call_id} is already in progress")]
    DuplicateCallId { call_id: CallId },

    #[error("Package initialization failed: {0}")]
    InitFailed(String),

    #[error("{0}")]
    Other(String),
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Read the message to see which types mismatch and where
2. Correct the caller to pass the expected BAML type
3. Add explicit casts/coercions in BAML code where intentional
4. Add host-side validation of argument types before invoking

Example fix

// before
engine.call("fn", "a string") // expects int
// after
engine.call("fn", 42)

fn assert_int(v: &BexExternalValue) -> Result<i64, EngineError> {
    match v { BexExternalValue::Int(i) => Ok(*i), other => Err(EngineError::TypeMismatch { message: format!("expected int, got {:?}", other) }) }
}

fn as_int(v: &BexExternalValue) -> Option<i64> {
    if let BexExternalValue::Int(i) = v { Some(*i) } else { None }
}

match result {
    Err(EngineError::TypeMismatch { message }) => eprintln!("bad arg: {message}"),
    Ok(v) => use(v),
    Err(e) => handle(e),
}

When it happens

Trigger: Calling engine APIs with arguments of the wrong BAML type — e.g. passing a string where an int is expected to a function-lookup or value-conversion API; runtime checks in builtins rejecting argument types.

Common situations: Signature drift after refactoring BAML functions; passing loosely-typed host values into typed engine entry points; schema/function updates changing parameter types.

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

• type `{ty}` can't be passed through auto-CLI; deliver it via
• baml.json.deserialize failed: {e:?}
• baml.json.serialize returned non-string value: {other:?}
• unsupported types for %= operator
• bitwise ^= requires integer operands

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