{"record":{"id":"23dd4bd1b990bf76","repo":"BoundaryML/baml","slug":"errloadlibrary","errorCode":"ErrLoadLibrary","errorMessage":"baml: failed loading shared library","messagePattern":"baml: failed loading shared library","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"engine/language_client_go/baml_go/lib_common.go","lineNumber":80,"sourceCode":"\treturn &http.Client{\n\t\tTransport: transport,\n\t\tTimeout:   5 * time.Minute,\n\t}\n}\n\n// setOrchestrionInternalFlag tries to set DD__tracer_internal=true using reflection.\n// This field is added by Orchestrion's code transformation.\nfunc setOrchestrionInternalFlag(transport *http.Transport) {\n\t// Use reflection to set the field if it exists\n\tval := reflect.ValueOf(transport).Elem()\n\tfield := val.FieldByName(\"DD__tracer_internal\")\n\tif field.IsValid() && field.CanSet() && field.Kind() == reflect.Bool {\n\t\tfield.SetBool(true)\n\t}\n}\n\nvar (\n\tErrLoadLibrary          = errors.New(\"baml: failed loading shared library\")\n\tErrNotSupportedPlatform = errors.New(\"baml: platform not supported (only Linux and MacOS amd64/arm64)\")\n\tErrDownloadFailed       = errors.New(\"baml: failed to download shared library\")\n\tErrCacheDir             = errors.New(\"baml: failed to determine or create cache directory\")\n\tErrChecksumMismatch     = errors.New(\"baml: downloaded library checksum mismatch\")\n\tErrVersionMismatch      = errors.New(\"baml: library version mismatch\")\n\tErrInitialization       = errors.New(\"baml: initialization failed\")\n)\n\nvar (\n\tbamlSharedLibraryPath = \"\"\n\tinitErr               error\n\tinitOnce              sync.Once\n\tbamlLibHandle         unsafe.Pointer\n\tlogger                *slog.Logger\n)\n\nfunc SetSharedLibraryPath(path string) {\n\tif bamlLibHandle != nil {","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_go/baml_go/lib_common.go#L62-L98","documentation":"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.","triggerScenarios":"initializeBaml -> findOrDownloadLibrary: os.Stat on the resolved bamlSharedLibraryPath fails (lib_common.go:136/138), or the subsequent dynamic.Open of the library fails.","commonSituations":"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.","solutions":["Read the wrapped detail: 'determined path ... does not exist' vs 'failed to stat' vs open/dlopen error to identify the stage","Ensure network access or vendor the library: allow findOrDownloadLibrary to download, or place the correct native library at the resolved path manually","Check the cache directory (os.UserCacheDir()/baml) is writable and contains the library for your GOOS/GOARCH","On Linux verify glibc and required shared objects exist (ldd on libbaml*.so); install missing system packages"],"exampleFix":"// before\n// CI container: HOME unset -> cache path invalid, library absent\n// after (Dockerfile)\nENV HOME=/root\nRUN mkdir -p /root/.cache && go test ./...  // library downloads on first init","handlingStrategy":"fallback","validationCode":"if _, err := os.Stat(libPath); err != nil {\n    return fmt.Errorf(\"baml library missing at %s: %w\", libPath, err)\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, baml.ErrLoadLibrary) {\n    log.Errorf(\"native library load failed: %v\", err)\n    // vendored library fallback or fail fast\n}","preventionTips":["Vendor or pre-download the native library in build/CI images","Run `ldd` on the .so in the target environment to catch missing system deps","Ensure the cache directory persists across container restarts"],"tags":["shared-library","initialization","platform"],"backgroundTag":"missing-dependency","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"}