BoundaryML/baml · error · BridgeError

Engine not initialized. Call create_baml_runtime first.

Error message

Engine not initialized. Call create_baml_runtime first.

What it means

BridgeError::NotInitialized is raised by the C-FFI/WASM bridge when a bridge function needs the global BAML runtime but the RUNTIME_INSTANCE slot is still empty (get_runtime in lib_native.rs / lib_wasm.rs). The engine must first be created via create_baml_runtime / initialize_runtime before any call_function, list functions, or other operations can be dispatched. It is a lifecycle/ordering error, not a data error.

Source

Thrown at baml_language/crates/bridge_cffi/src/error.rs:10

//! Error types for bridge_cffi.

use thiserror::Error;

/// Errors that can occur during bridge operations.
#[derive(Debug, Error)]
pub enum BridgeError {
    #[error(transparent)]
    Ctypes(#[from] bridge_ctypes::CtypesError),
    #[error("Engine not initialized. Call create_baml_runtime first.")]
    NotInitialized,

    #[error("Project not initialized")]
    ProjectNotInitialized,

    #[error("Engine lock poisoned")]
    LockPoisoned,

    #[error("{0}")]
    Runtime(#[from] bex_project::RuntimeError),

    #[error("CallFunctionArgs.call_target must be set")]
    MissingCallTarget,

    #[error("type arguments are not supported when invoking a BAML function handle")]
    FunctionHandleTypeArgs,

    #[error("Function not found: {name}")]

View on GitHub (pinned to bd85ce9dee)

Solutions

Call create_baml_runtime (or initialize_runtime) with the project root and source files before any other bridge call.
Check the result of the initialization call and handle its error instead of ignoring it.
Gate all bridge operations behind an initialized flag/promise so calls cannot run before setup completes.
If the runtime was taken (take_runtime) or shut down, reinstall it with replace_runtime before further calls.

Example fix

// before
result = lib.call_function(ctx, "MyFunc", args)  // engine never created
// after
lib.create_baml_runtime(root_path, files)
result = lib.call_function(ctx, "MyFunc", args)

Defensive patterns

Strategy: try-catch

Validate before calling

// host side (Python ctypes example)
def ensure_engine_ready():
    if not _engine_initialized:
        raise RuntimeError("call create_baml_runtime before any bridge call")

Try / catch

try:
    result = lib.call_function(ctx, name, args)
except BridgeError as e:
    if "not initialized" in str(e):
        lib.create_baml_runtime(root_path, files)
        result = lib.call_function(ctx, name, args)
    else:
        raise

Prevention

Always run create_baml_runtime/initialize_runtime at startup, before any other bridge call.
Check the init call's return value; do not swallow initialization failures.
Serialize bridge calls behind an initialized flag or async init promise.
Never call take_runtime without reinstating the runtime afterwards.

When it happens

Trigger: Calling any bridge entry point that internally invokes get_runtime() (e.g. call_function and other dispatch APIs) before create_baml_runtime/initialize_runtime has succeeded; after take_runtime() or a shutdown cleared the global; when an earlier initialize_runtime call failed so the slot was never populated.

Common situations: Embedding BAML via ctypes/C-FFI and forgetting the init call at startup; initialization failing silently earlier (bad project files) and a later call surfacing as NotInitialized; running operations in a fresh thread/process where the engine was never created; WASM host invoking functions before the async init resolves.

Related errors

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