{"record":{"id":"b533d2b30eecfff6","repo":"BoundaryML/baml","slug":"failed-to-create-baml-runtime","errorCode":null,"errorMessage":"failed to create BAML runtime","messagePattern":"failed to create BAML runtime","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"engine/language_client_go/baml_go/exports.go","lineNumber":33,"sourceCode":"#include <stdlib.h>\n#include <stdint.h>\n#include <string.h>\n*/\nimport \"C\"\n\nfunc CreateBamlRuntime(rootPath string, srcFilesJson string, envVarsJson string) (unsafe.Pointer, error) {\n\tcRootPath := C.CString(rootPath)\n\tdefer C.free(unsafe.Pointer(cRootPath))\n\n\tcSrcFilesJson := C.CString(srcFilesJson)\n\tdefer C.free(unsafe.Pointer(cSrcFilesJson))\n\n\tcEnvVarsJson := C.CString(envVarsJson)\n\tdefer C.free(unsafe.Pointer(cEnvVarsJson))\n\n\truntime := C.WrapCreateBamlRuntime(cRootPath, cSrcFilesJson, cEnvVarsJson)\n\tif runtime == nil {\n\t\treturn nil, fmt.Errorf(\"failed to create BAML runtime\")\n\t}\n\treturn runtime, nil\n}\n\nfunc DestroyBamlRuntime(runtime unsafe.Pointer) error {\n\tC.WrapDestroyBamlRuntime(runtime)\n\treturn nil\n}\n\nfunc BamlVersion() string {\n\tbuf := C.WrapVersion()\n\tdefer C.WrapFreeBuffer(buf)\n\tif buf.ptr == nil || buf.len == 0 {\n\t\treturn \"\"\n\t}\n\treturn string(C.GoBytes(unsafe.Pointer(buf.ptr), C.int32_t(buf.len)))\n}\n","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_go/baml_go/exports.go#L15-L51","documentation":"CreateBamlRuntime calls the C FFI function WrapCreateBamlRuntime with the root path, source files, and environment variables; when the underlying BAML runtime fails to initialize, the C layer returns a nil pointer and this Go error is produced. It means the BAML runtime could not be constructed at all, so no function calls (prompt generation, LLM invocation) can succeed. The root cause details are inside the native runtime, not surfaced in this error message.","triggerScenarios":"Calling CreateBamlRuntime (exposed as CreateRuntime) when the C FFI returns nil: invalid root path, malformed source-files JSON, invalid env-vars JSON, or native runtime internal failure during construction.","commonSituations":"Deploying to an environment where BAML_SOURCE_ROOT or the baml_src directory is missing or wrong; passing an environment map that fails to serialize correctly; native runtime crashing on unsupported project files or incompatible baml-cli-generated artifacts.","solutions":["Verify the root path passed to CreateRuntime points at the directory containing baml_src and that the path exists and is readable","Check that envVarsJson is valid JSON produced from a map[string]string of environment variables (especially LLM API keys)","Ensure the native BAML shared library version matches the Go client version (see ErrVersionMismatch in lib_common.go)","Enable BAML debug logging / run the baml CLI against the same source files to reproduce the native-side failure"],"exampleFix":"// before\nruntime, err := baml.CreateRuntime(\"\") // empty root path\n// after\nruntime, err := baml.CreateRuntime(\"/app\") // path containing baml_src/","handlingStrategy":"try-catch","validationCode":"if info, err := os.Stat(filepath.Join(rootDir, \"baml_src\")); err != nil || !info.IsDir() {\n    return fmt.Errorf(\"baml_src not found under %s\", rootDir)\n}","typeGuard":"func runtimeReady(rt *baml.Runtime) bool { return rt != nil }","tryCatchPattern":"rt, err := baml.CreateRuntime(rootDir)\nif err != nil {\n    return fmt.Errorf(\"baml runtime init failed: %w\", err)\n}","preventionTips":["Validate the baml_src directory exists and is readable at process startup","Pass a complete, non-empty environment map including all provider API keys","Keep the Go client and native library versions in lockstep"],"tags":["ffi","runtime-initialization","cgo"],"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"}