BoundaryML/baml · critical

ErrLoadLibrary

ErrLoadLibrary

Error message

baml: failed loading shared library

What it means

ErrLoadLibrary is the sentinel error for failures while locating, downloading, stat-ing, or dlopen-ing the BAML native shared library. initializeBaml and findOrDownloadLibrary wrap every such failure with %w so callers can match with errors.Is. Typical causes are a missing library file at the resolved path or a dlopen failure due to missing system dependencies.

Source

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

	return &http.Client{
		Transport: transport,
		Timeout:   5 * time.Minute,
	}
}

// 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 {

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Read the wrapped detail: 'determined path ... does not exist' vs 'failed to stat' vs open/dlopen error to identify the stage
2. Ensure network access or vendor the library: allow findOrDownloadLibrary to download, or place the correct native library at the resolved path manually
3. Check the cache directory (os.UserCacheDir()/baml) is writable and contains the library for your GOOS/GOARCH
4. On Linux verify glibc and required shared objects exist (ldd on libbaml*.so); install missing system packages

Example fix

// before
// CI container: HOME unset -> cache path invalid, library absent
// after (Dockerfile)
ENV HOME=/root
RUN mkdir -p /root/.cache && go test ./...  // library downloads on first init

if _, err := os.Stat(libPath); err != nil {
    return fmt.Errorf("baml library missing at %s: %w", libPath, err)
}

if errors.Is(err, baml.ErrLoadLibrary) {
    log.Errorf("native library load failed: %v", err)
    // vendored library fallback or fail fast
}

When it happens

Trigger: initializeBaml -> findOrDownloadLibrary: os.Stat on the resolved bamlSharedLibraryPath fails (lib_common.go:136/138), or the subsequent dynamic.Open of the library fails.

Common situations: First run on a machine with no network access so the library was never downloaded; read-only or cleaned cache directory; library downloaded for the wrong platform/ARCH; missing system libs (e.g. glibc version too old) making dlopen fail.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• ErrVersionMismatch
• ErrInitialization
• panic(initErr)
• unsupported pack target `{target_triple}`
• -32002

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