{"record":{"id":"24fe620fa51c2efa","repo":"BoundaryML/baml","slug":"errinitialization","errorCode":"ErrInitialization","errorMessage":"baml: initialization failed","messagePattern":"baml: initialization failed","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"engine/language_client_go/baml_go/lib_common.go","lineNumber":86,"sourceCode":"// 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 {\n\t\tlogger.Warn(\"SetSharedLibraryPath called after BAML library was initialized. Path ignored.\", \"path\", path)\n\t\treturn\n\t}\n\tbamlSharedLibraryPath = path\n}\n","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_go/baml_go/lib_common.go#L68-L104","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Unwrap the error chain (errors.Is / %v print) to find the wrapped sentinel — ErrCacheDir, ErrDownloadFailed, ErrChecksumMismatch, or ErrLoadLibrary — and fix that root cause","Ensure HOME/cache dir is writable and network access to the release host works on first run","For the empty-path branch, capture the GOOS/GOARCH and versions and report it as a bug in findOrDownloadLibrary","Initialize once at process startup (not lazily) so init failures surface loudly in logs and health checks"],"exampleFix":"// before\n// swallowing init error at startup; failure only appears at first LLM call\n// after\nif err := baml.EnsureInitialized(); err != nil {\n    log.Fatalf(\"baml init failed: %+v\", err) // prints full wrapped chain\n}","handlingStrategy":"try-catch","validationCode":"if err := baml.EnsureInitialized(); err != nil {\n    log.Fatalf(\"baml initialization failed: %+v\", err) // surface full wrapped chain\n}","typeGuard":null,"tryCatchPattern":"err := baml.Initialize()\nswitch {\ncase errors.Is(err, baml.ErrCacheDir):\n    fixCacheEnv()\ncase errors.Is(err, baml.ErrDownloadFailed):\n    useVendoredLibrary()\ncase errors.Is(err, baml.ErrInitialization):\n    log.Fatalf(\"baml init: %v\", err)\n}","preventionTips":["Initialize BAML eagerly at startup so init errors fail fast with full error chains","Always inspect the wrapped sentinel via errors.Is rather than string matching","Verify cache-dir writability and network egress as standard pre-deploy checks"],"tags":["initialization","shared-library","error-wrapping"],"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"}