BoundaryML/baml · error

ErrInitialization

ErrInitialization

Error message

baml: initialization failed

What it means

ErrInitialization is the top-level sentinel returned by initializeBaml when library path discovery fails (findOrDownloadLibrary returns an error) or, at lib_common.go:131, when discovery succeeds but yields an empty path — an unexpected state. The underlying cause is wrapped with %w; match with errors.Is(err, ErrInitialization) and inspect the chain.

Source

Thrown at engine/language_client_go/baml_go/lib_common.go:86

// setOrchestrionInternalFlag tries to set DD__tracer_internal=true using reflection.
// This field is added by Orchestrion's code transformation.
func setOrchestrionInternalFlag(transport *http.Transport) {
	// Use reflection to set the field if it exists
	val := reflect.ValueOf(transport).Elem()
	field := val.FieldByName("DD__tracer_internal")
	if field.IsValid() && field.CanSet() && field.Kind() == reflect.Bool {
		field.SetBool(true)
	}
}

var (
	ErrLoadLibrary          = errors.New("baml: failed loading shared library")
	ErrNotSupportedPlatform = errors.New("baml: platform not supported (only Linux and MacOS amd64/arm64)")
	ErrDownloadFailed       = errors.New("baml: failed to download shared library")
	ErrCacheDir             = errors.New("baml: failed to determine or create cache directory")
	ErrChecksumMismatch     = errors.New("baml: downloaded library checksum mismatch")
	ErrVersionMismatch      = errors.New("baml: library version mismatch")
	ErrInitialization       = errors.New("baml: initialization failed")
)

var (
	bamlSharedLibraryPath = ""
	initErr               error
	initOnce              sync.Once
	bamlLibHandle         unsafe.Pointer
	logger                *slog.Logger
)

func SetSharedLibraryPath(path string) {
	if bamlLibHandle != nil {
		logger.Warn("SetSharedLibraryPath called after BAML library was initialized. Path ignored.", "path", path)
		return
	}
	bamlSharedLibraryPath = path
}

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Unwrap the error chain (errors.Is / %v print) to find the wrapped sentinel — ErrCacheDir, ErrDownloadFailed, ErrChecksumMismatch, or ErrLoadLibrary — and fix that root cause
2. Ensure HOME/cache dir is writable and network access to the release host works on first run
3. For the empty-path branch, capture the GOOS/GOARCH and versions and report it as a bug in findOrDownloadLibrary
4. Initialize once at process startup (not lazily) so init failures surface loudly in logs and health checks

Example fix

// before
// swallowing init error at startup; failure only appears at first LLM call
// after
if err := baml.EnsureInitialized(); err != nil {
    log.Fatalf("baml init failed: %+v", err) // prints full wrapped chain
}

if err := baml.EnsureInitialized(); err != nil {
    log.Fatalf("baml initialization failed: %+v", err) // surface full wrapped chain
}

err := baml.Initialize()
switch {
case errors.Is(err, baml.ErrCacheDir):
    fixCacheEnv()
case errors.Is(err, baml.ErrDownloadFailed):
    useVendoredLibrary()
case errors.Is(err, baml.ErrInitialization):
    log.Fatalf("baml init: %v", err)
}

When it happens

Trigger: initializeBaml at lib_common.go:127 wrapping any findOrDownloadLibrary error (download, cache-dir, checksum, load failures), and :131 when bamlSharedLibraryPath ends up empty despite a nil error.

Common situations: First-run environments where download/cache preconditions fail; a genuine bug where path discovery silently succeeds without setting the path; any of the wrapped sentinel errors (ErrCacheDir, ErrDownloadFailed, ErrChecksumMismatch, ErrLoadLibrary) surfacing during sync.Once init.

Related errors

• ErrLoadLibrary
• ErrVersionMismatch
• panic(initErr)
• -32002
• Package initialization failed: {0}

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