BoundaryML/baml · critical

failed to create BAML runtime

Error message

failed to create BAML runtime

What it means

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.

Source

Thrown at engine/language_client_go/baml_go/exports.go:33

#include <stdlib.h>
#include <stdint.h>
#include <string.h>
*/
import "C"

func CreateBamlRuntime(rootPath string, srcFilesJson string, envVarsJson string) (unsafe.Pointer, error) {
	cRootPath := C.CString(rootPath)
	defer C.free(unsafe.Pointer(cRootPath))

	cSrcFilesJson := C.CString(srcFilesJson)
	defer C.free(unsafe.Pointer(cSrcFilesJson))

	cEnvVarsJson := C.CString(envVarsJson)
	defer C.free(unsafe.Pointer(cEnvVarsJson))

	runtime := C.WrapCreateBamlRuntime(cRootPath, cSrcFilesJson, cEnvVarsJson)
	if runtime == nil {
		return nil, fmt.Errorf("failed to create BAML runtime")
	}
	return runtime, nil
}

func DestroyBamlRuntime(runtime unsafe.Pointer) error {
	C.WrapDestroyBamlRuntime(runtime)
	return nil
}

func BamlVersion() string {
	buf := C.WrapVersion()
	defer C.WrapFreeBuffer(buf)
	if buf.ptr == nil || buf.len == 0 {
		return ""
	}
	return string(C.GoBytes(unsafe.Pointer(buf.ptr), C.int32_t(buf.len)))
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Verify the root path passed to CreateRuntime points at the directory containing baml_src and that the path exists and is readable
2. Check that envVarsJson is valid JSON produced from a map[string]string of environment variables (especially LLM API keys)
3. Ensure the native BAML shared library version matches the Go client version (see ErrVersionMismatch in lib_common.go)
4. Enable BAML debug logging / run the baml CLI against the same source files to reproduce the native-side failure

Example fix

// before
runtime, err := baml.CreateRuntime("") // empty root path
// after
runtime, err := baml.CreateRuntime("/app") // path containing baml_src/

if info, err := os.Stat(filepath.Join(rootDir, "baml_src")); err != nil || !info.IsDir() {
    return fmt.Errorf("baml_src not found under %s", rootDir)
}

func runtimeReady(rt *baml.Runtime) bool { return rt != nil }

rt, err := baml.CreateRuntime(rootDir)
if err != nil {
    return fmt.Errorf("baml runtime init failed: %w", err)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• baml.panics.HostContractViolation
• Engine not initialized. Call create_baml_runtime first.
• Project not initialized
• CallFunctionArgs.call_target must be set
• type arguments are not supported when invoking a BAML functi

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