{"record":{"id":"a25deb430f89edf8","repo":"BoundaryML/baml","slug":"s-lib-unix","errorCode":null,"errorMessage":"%s","messagePattern":"%s","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"engine/language_client_go/baml_go/lib_unix.go","lineNumber":67,"sourceCode":"\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())\n\n\tif symbol == nil {\n\t\terrMsg := fmt.Sprintf(\"dlsym error for %s\", name)\n\t\tif errStr != \"\" {\n\t\t\terrMsg += fmt.Sprintf(\": %s\", errStr)\n\t\t} else {\n\t\t\terrMsg += \": symbol not found\"\n\t\t}\n\t\treturn nil, fmt.Errorf(\"%s\", errMsg)\n\t}\n\treturn symbol, nil\n}\n\n// closeLibrary closes the loaded library\nfunc closeLibrary(handle unsafe.Pointer) error {\n\tif handle == nil {\n\t\treturn nil\n\t}\n\tif C.dlclose(handle) != 0 {\n\t\terrStr := C.GoString(C.dlerror())\n\t\tif errStr != \"\" {\n\t\t\treturn fmt.Errorf(\"dlclose failed: %s\", errStr)\n\t\t}\n\t\treturn fmt.Errorf(\"dlclose failed\")\n\t}\n\treturn nil\n}","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_go/baml_go/lib_unix.go#L49-L85","documentation":"After a failed C.dlsym lookup, getSymbol builds a message \"dlsym error for <name>[: <dlerror> | : symbol not found]\" and returns it via fmt.Errorf(\"%s\", ...). It means the requested exported symbol does not exist in the loaded native library (or version mismatch changed its name).","triggerScenarios":"dlsym(handle, name) returns nil with a non-empty dlerror string, or returns nil with empty error — symbol absent from the shared library.","commonSituations":"Go bindings version out of sync with the downloaded native library (renamed/removed exports); loading an old cached .so with newer client code; stripped binaries missing exported symbols.","solutions":["Re-download/reinstall the native library so its version matches the Go bindings","Verify the symbol exists: `nm -D <path> | grep <name>` (or `nm -gU` on macOS)","Clear stale cached library versions and pin matching versions of the client package and native artifact","Check the appended dlerror detail for loader-level problems (relocations, dependency symbols)"],"exampleFix":"// before\nnm -D ~/.cache/baml/native/libbaml.so | grep baml_fn  -> not found (v0.51 lib with v0.55 bindings)\n// after\ngo get github.com/boundaryml/baml/go@v0.51  # align bindings with cached lib\n# or clear cache so the matching native lib is re-downloaded","handlingStrategy":"try-catch","validationCode":"out, err := exec.Command(\"nm\", \"-D\", libPath).Output()\nif err != nil || !strings.Contains(string(out), symbolName) {\n    return fmt.Errorf(\"symbol %s absent from %s; version mismatch?\", symbolName, libPath)\n}","typeGuard":null,"tryCatchPattern":"sym, err := getSymbol(handle, name)\nif err != nil && strings.Contains(err.Error(), \"dlsym error for\") {\n    // artifact/bindings mismatch: refresh the native library to match client version\n    return refreshLibraryAndRetry(handle, name)\n}","preventionTips":["Keep the Go client package and native library versions in lockstep","Clear the native library cache when upgrading the client","Spot-check exported symbols with nm/objdump after installs"],"tags":["go","dlsym","native-library","version-mismatch"],"backgroundTag":"symbol-not-found","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"}