{"record":{"id":"5c836907e4e40e5b","repo":"BoundaryML/baml","slug":"w-library-or-dependency-not-found","errorCode":null,"errorMessage":"%w (library or dependency not found)","messagePattern":"%w \\(library or dependency not found\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"engine/language_client_go/baml_go/lib_unix.go","lineNumber":40,"sourceCode":"// 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) {\n\tif handle == nil {\n\t\treturn nil, fmt.Errorf(\"library handle is nil when looking up symbol '%s'\", name)\n\t}\n\n\tcName := C.CString(name)\n\tdefer C.free(unsafe.Pointer(cName))\n\n\tC.dlerror() // Clear any existing error\n\tsymbol := C.dlsym(handle, cName)\n\terrStr := C.GoString(C.dlerror())","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_go/baml_go/lib_unix.go#L22-L58","documentation":"If dlerror() contains \"image not found\" (macOS) or \"no such file or directory\" (Linux), loadLibrary appends \"(library or dependency not found)\". The library itself or one of its transitive dependencies could not be located by the loader.","triggerScenarios":"dlopen fails with ENOENT-style errors: the .dylib/.so path is wrong, or a dependent shared library referenced by the artifact is absent (common macOS \"image not found\").","commonSituations":"Homebrew/dependency version changes changing install_name paths; missing system libraries in slim Docker images; macOS dylib expecting an @rpath that isn't set.","solutions":["On macOS run `otool -L <path>` and install/fix the listed missing dependency (e.g. via brew)","On Linux run `ldd <path>` and install the missing shared object","Re-download the native library to restore a deleted artifact","In slim containers, add the required runtime packages (e.g. libgcc, glibc compat) to the image"],"exampleFix":"// before (docker slim image)\nFROM golang:1.22-alpine   # missing glibc deps -> \"no such file or directory\"\n// after\nFROM golang:1.22-bookworm  # or: apk add libc6-compat","handlingStrategy":"validation","validationCode":"cmd := exec.Command(\"ldd\", libPath) // otool -L on darwin\nout, err := cmd.Output()\nif err != nil || strings.Contains(string(out), \"not found\") {\n    return fmt.Errorf(\"missing dependency for %s\", libPath)\n}","typeGuard":null,"tryCatchPattern":"if err := loadLibrary(path); err != nil {\n    if strings.Contains(err.Error(), \"library or dependency not found\") {\n        // run ldd/otool, install the missing dependency, retry\n        return installDepsAndRetry(path)\n    }\n    return err\n}","preventionTips":["Bundle or vendor the dylib's dependency chain (fix @rpath on macOS)","Use base images with complete libc/runtime support","Re-run dependency checks after upgrading OS packages or Homebrew libraries"],"tags":["go","dlopen","missing-dependency","native-library"],"backgroundTag":"missing-dependency","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}