{"record":{"id":"df28bb705f2bed7d","repo":"BoundaryML/baml","slug":"engine-not-initialized-call-create-baml-runtime-first","errorCode":null,"errorMessage":"Engine not initialized. Call create_baml_runtime first.","messagePattern":"Engine not initialized\\. Call create_baml_runtime first\\.","errorType":"exception","errorClass":"BridgeError","httpStatus":null,"severity":"error","filePath":"baml_language/crates/bridge_cffi/src/error.rs","lineNumber":10,"sourceCode":"//! Error types for bridge_cffi.\n\nuse thiserror::Error;\n\n/// Errors that can occur during bridge operations.\n#[derive(Debug, Error)]\npub enum BridgeError {\n    #[error(transparent)]\n    Ctypes(#[from] bridge_ctypes::CtypesError),\n    #[error(\"Engine not initialized. Call create_baml_runtime first.\")]\n    NotInitialized,\n\n    #[error(\"Project not initialized\")]\n    ProjectNotInitialized,\n\n    #[error(\"Engine lock poisoned\")]\n    LockPoisoned,\n\n    #[error(\"{0}\")]\n    Runtime(#[from] bex_project::RuntimeError),\n\n    #[error(\"CallFunctionArgs.call_target must be set\")]\n    MissingCallTarget,\n\n    #[error(\"type arguments are not supported when invoking a BAML function handle\")]\n    FunctionHandleTypeArgs,\n\n    #[error(\"Function not found: {name}\")]","sourceCodeStart":1,"sourceCodeEnd":28,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/baml_language/crates/bridge_cffi/src/error.rs#L1-L28","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nresult = lib.call_function(ctx, \"MyFunc\", args)  // engine never created\n// after\nlib.create_baml_runtime(root_path, files)\nresult = lib.call_function(ctx, \"MyFunc\", args)","handlingStrategy":"try-catch","validationCode":"// host side (Python ctypes example)\ndef ensure_engine_ready():\n    if not _engine_initialized:\n        raise RuntimeError(\"call create_baml_runtime before any bridge call\")","typeGuard":null,"tryCatchPattern":"try:\n    result = lib.call_function(ctx, name, args)\nexcept BridgeError as e:\n    if \"not initialized\" in str(e):\n        lib.create_baml_runtime(root_path, files)\n        result = lib.call_function(ctx, name, args)\n    else:\n        raise","preventionTips":["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."],"tags":["initialization","ffi","lifecycle","rust"],"backgroundTag":"module-init-failed","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}