{"record":{"id":"b61bb5c7cf4c5bc0","repo":"BoundaryML/baml","slug":"panic-initerr","errorCode":null,"errorMessage":"panic(initErr)","messagePattern":"panic\\(initErr\\)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"engine/language_client_go/baml_go/lib_common.go","lineNumber":110,"sourceCode":"\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\nfunc init() {\n\tinitSlog() // Initialize the logger first\n\tinitOnce.Do(func() {\n\t\tinitErr = initializeBaml()\n\t\tif initErr != nil {\n\t\t\tpanic(initErr)\n\t\t}\n\t})\n}\n\nfunc GetInitError() error {\n\treturn initErr\n}\n\nfunc initializeBaml() error {\n\tif !isSupportedPlatform() {\n\t\terr := fmt.Errorf(\"%w: OS=%s Arch=%s\", ErrNotSupportedPlatform, runtime.GOOS, runtime.GOARCH)\n\t\treturn err\n\t}\n\n\terr := findOrDownloadLibrary()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"%w: %w\", ErrInitialization, err)\n\t}","sourceCodeStart":92,"sourceCodeEnd":128,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_go/baml_go/lib_common.go#L92-L128","documentation":"The baml_go package runs its library setup inside a package-level init() guarded by sync.Once. If initializeBaml() returns any error (unsupported platform, missing/corrupt shared library, version mismatch, cache-dir failure), init() panics with that error, aborting the whole program. It is thrown because the FFI binding cannot function at all without the native baml_cffi library loaded, and the library treats that as unrecoverable rather than returning errors from every API.","triggerScenarios":"Importing package baml_go (any import chain) when initializeBaml() fails: GOOS/GOARCH unsupported, findOrDownloadLibrary() fails (bad BAML_LIBRARY_PATH, BAML_LIBRARY_DISABLE_DOWNLOAD=true with no cached/system library, download network failure), discovered path stat fails, loadLibrary fails, or BamlVersion() != VERSION.","commonSituations":"Cross-compiling to a platform BAML does not ship (e.g. linux/386, freebsd); running in an air-gapped CI sandbox with downloads disabled and no pre-provisioned library; corrupted or stale cached library in ~/.cache/baml/libs/<version>; BAML_LIBRARY_PATH pointing at a deleted or wrong-arch file; mixing baml Go package version with an older pre-downloaded libbaml.so in /usr/local/lib.","solutions":["Read the wrapped error in the panic message to identify the root cause (platform, download, path, load, or version mismatch).","If the platform is unsupported, build/run on linux/darwin/windows amd64 or arm64, or pin the app to a supported target.","Pre-provision the native library: set BAML_LIBRARY_PATH to a valid libbaml_cffi-<triple>.so/dylib/dll of the matching version, or allow downloads so the cache is populated.","If download is disabled (BAML_LIBRARY_DISABLE_DOWNLOAD=true), either enable it or clear the stale cache dir (or set BAML_CACHE_DIR) so a fresh copy is fetched.","In tests, import the package only when GetInitError()-able platforms are used, or guard with a build tag; the panic occurs at init time so it cannot be caught with recover from user code at call time."],"exampleFix":"// before: app crashes at startup on an offline CI runner\nimport _ \"github.com/boundaryml/baml/engine/language_client_go/baml_go\"\n\n// after: provision the library ahead of time in the image/CI step\n// RUN curl -L -o /usr/local/lib/libbaml_cffi-x86_64-unknown-linux-gnu.so \\\n//   https://github.com/boundaryml/baml/releases/download/v0.226.2/libbaml_cffi-x86_64-unknown-linux-gnu.so\n// ENV BAML_LIBRARY_PATH=/usr/local/lib/libbaml_cffi-x86_64-unknown-linux-gnu.so\nimport _ \"github.com/boundaryml/baml/engine/language_client_go/baml_go\"","handlingStrategy":"try-catch","validationCode":"// go env check before building/running\ngo env GOOS GOARCH  # must be linux|darwin|windows + amd64|arm64\n// shell check before starting the binary:\n# test -f \"${BAML_LIBRARY_PATH:-$HOME/.cache/baml/libs/0.226.2/libbaml_cffi-x86_64-unknown-linux-gnu.so}\"","typeGuard":"if err := baml_go.GetInitError(); err != nil { /* init already panicked; this only helps in builds where init did not run */ }","tryCatchPattern":"// The panic happens in package init, before your code runs. Guard at the deployment level:\n// in Go you can recover only in a deferred func of main, but init panics abort the process;\n// instead, run a preflight subprocess or check env/platform in CI:\nfunc preflight() error {\n    if runtime.GOOS != \"linux\" && runtime.GOOS != \"darwin\" && runtime.GOOS != \"windows\" {\n        return fmt.Errorf(\"unsupported GOOS %s\", runtime.GOOS)\n    }\n    if runtime.GOARCH != \"amd64\" && runtime.GOARCH != \"arm64\" {\n        return fmt.Errorf(\"unsupported GOARCH %s\", runtime.GOARCH)\n    }\n    return nil\n}","preventionTips":["Pin your build targets (CI matrix, docker --platform) to linux/darwin/windows amd64/arm64 only.","Pre-download or vendor the correct libbaml_cffi for your exact baml Go version into the image and set BAML_LIBRARY_PATH.","Never rely on network downloads at container startup in sandboxed/air-gapped environments; set BAML_LIBRARY_DISABLE_DOWNLOAD only when a library is pre-provisioned.","After upgrading the baml Go module, clear or refresh the library cache so versions match (ErrVersionMismatch otherwise panics the same way).","Set BAML_LOG=DEBUG during deployment troubleshooting to see which discovery step fails."],"tags":["go","panic","initialization","ffi","shared-library"],"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"}