{"record":{"id":"5b2a2b1ac6f9a8b1","repo":"BoundaryML/baml","slug":"errloadlibrary-dlopen-error-for-s-s","errorCode":"ErrLoadLibrary","errorMessage":"dlopen error for %s: %s","messagePattern":"dlopen error for (.+?): (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"engine/language_client_go/baml_go/lib_unix.go","lineNumber":30,"sourceCode":"#include <string.h>\n#include <stdint.h>\n*/\nimport \"C\"\nimport (\n\t\"fmt\"\n\t\"strings\"\n\t\"unsafe\"\n)\n\n// loadLibrary loads the shared library using dlopen\nfunc loadLibrary(path string) (unsafe.Pointer, error) {\n\tcPath := C.CString(path)\n\tdefer C.free(unsafe.Pointer(cPath))\n\n\thandle := C.dlopen(cPath, C.RTLD_LAZY|C.RTLD_LOCAL)\n\tif handle == nil {\n\t\tdlErrStr := C.GoString(C.dlerror())\n\t\tdlopenErr := fmt.Errorf(\"dlopen error for %s: %s\", path, dlErrStr)\n\t\tif strings.Contains(dlErrStr, \"mach-o, but wrong architecture\") || strings.Contains(dlErrStr, \"wrong ELF class\") {\n\t\t\tdlopenErr = fmt.Errorf(\"%w (architecture mismatch)\", dlopenErr)\n\t\t} else if strings.Contains(dlErrStr, \"cannot open shared object file\") {\n\t\t\tif strings.Contains(dlErrStr, \"Permission denied\") {\n\t\t\t\tdlopenErr = fmt.Errorf(\"%w (permission denied)\", dlopenErr)\n\t\t\t} else {\n\t\t\t\tdlopenErr = fmt.Errorf(\"%w (file not found or inaccessible)\", dlopenErr)\n\t\t\t}\n\t\t} else if strings.Contains(dlErrStr, \"image not found\") || strings.Contains(dlErrStr, \"no such file or directory\") {\n\t\t\tdlopenErr = fmt.Errorf(\"%w (library or dependency not found)\", dlopenErr)\n\t\t}\n\t\treturn nil, dlopenErr\n\t}\n\treturn handle, nil\n}\n\n// getSymbol retrieves a symbol from the loaded library\nfunc getSymbol(handle unsafe.Pointer, name string) (unsafe.Pointer, error) {","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_go/baml_go/lib_unix.go#L12-L48","documentation":"loadLibrary in lib_unix.go calls C.dlopen to load the BAML native shared library; when dlopen returns nil the raw dlerror() string is wrapped with the library path and tagged code=ErrLoadLibrary. It is the base error for all dynamic-library loading failures on unix/macOS.","triggerScenarios":"C.dlopen(path, RTLD_LAZY|RTLD_LOCAL) returns nil during loadLibrary — wrong path, missing dependencies, architecture mismatch, or permissions — and none of the more specific suffixes match.","commonSituations":"Corrupt or partially downloaded .so/.dylib; missing transitive native dependencies; wrong platform artifact shipped; LD_LIBRARY_PATH/DYLD_LIBRARY_PATH misconfigured.","solutions":["Verify the library file exists at `path` and is a valid shared object for the current OS (`file <path>`)","Re-download/reinstall the BAML native library to repair a corrupt artifact","Check dependent shared libraries (`ldd <path>` / `otool -L <path>`) and install missing ones","Confirm the artifact matches your OS/arch (amd64 vs arm64)","Inspect the wrapped dlerror() detail string for the precise OS-level cause"],"exampleFix":"// before\nhandle := C.dlopen(cPath, C.RTLD_LAZY|C.RTLD_LOCAL) // nil, dlerror: wrong ELF class\n// after (fix mismatch)\n// file baml_cls_abi.so -> ELF 64-bit LSB x86-64 but running arm64:\n// reinstall the arm64 build\nexport TARGET_ARCH=arm64 && go run ./gen/download.go","handlingStrategy":"validation","validationCode":"info, err := os.Stat(libPath)\nif err != nil || info.IsDir() {\n    return fmt.Errorf(\"native library missing at %s\", libPath)\n}\nout, _ := exec.Command(\"file\", libPath).Output() // check ELF/Mach-O matches OS","typeGuard":null,"tryCatchPattern":"handle, err := loadLibrary(path)\nif errors.Is(err, ErrLoadLibrary) {\n    // inspect wrapped dlerror detail; repair artifact or deps before retry\n    return repairAndReload(path)\n}","preventionTips":["Always complete the native-library download step before first use","Verify artifact OS/arch with `file` after download","Keep LD_LIBRARY_PATH / DYLD paths consistent in all environments"],"tags":["go","dlopen","native-library","unix"],"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"}