{"record":{"id":"f76ec1b6a4ef49b5","repo":"mudler/LocalAI","slug":"parakeet-cpp-dlopen-q-w","errorCode":null,"errorMessage":"parakeet-cpp: dlopen %q: %w","messagePattern":"parakeet-cpp: dlopen %q: %w","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"backend/go/parakeet-cpp/main.go","lineNumber":42,"sourceCode":"\ntype LibFuncs struct {\n\tFuncPtr any\n\tName    string\n}\n\nfunc main() {\n\tlibName := os.Getenv(\"PARAKEET_LIBRARY\")\n\tif libName == \"\" {\n\t\tif runtime.GOOS == \"darwin\" {\n\t\t\tlibName = \"libparakeet.dylib\"\n\t\t} else {\n\t\t\tlibName = \"libparakeet.so\"\n\t\t}\n\t}\n\n\tlib, err := purego.Dlopen(libName, purego.RTLD_NOW|purego.RTLD_GLOBAL)\n\tif err != nil {\n\t\tpanic(fmt.Errorf(\"parakeet-cpp: dlopen %q: %w\", libName, err))\n\t}\n\n\t// Bound 1:1 to parakeet_capi.h. The C-API returns malloc'd char*\n\t// buffers from transcribe_*; we register those as uintptr so we get\n\t// the raw pointer back and can call parakeet_capi_free_string on it\n\t// (purego's string return would copy and forget the original pointer,\n\t// leaking it on every call).\n\tlibFuncs := []LibFuncs{\n\t\t{&CppAbiVersion, \"parakeet_capi_abi_version\"},\n\t\t{&CppLoad, \"parakeet_capi_load\"},\n\t\t{&CppFree, \"parakeet_capi_free\"},\n\t\t{&CppTranscribePath, \"parakeet_capi_transcribe_path\"},\n\t\t{&CppTranscribePathJSON, \"parakeet_capi_transcribe_path_json\"},\n\t\t{&CppStreamBegin, \"parakeet_capi_stream_begin\"},\n\t\t{&CppStreamFeed, \"parakeet_capi_stream_feed\"},\n\t\t{&CppStreamFinalize, \"parakeet_capi_stream_finalize\"},\n\t\t{&CppStreamFree, \"parakeet_capi_stream_free\"},\n\t\t{&CppFreeString, \"parakeet_capi_free_string\"},","sourceCodeStart":24,"sourceCodeEnd":60,"githubUrl":"https://github.com/mudler/LocalAI/blob/44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26/backend/go/parakeet-cpp/main.go#L24-L60","documentation":"Startup panic of the Go parakeet-cpp backend when purego.Dlopen fails to load the Parakeet transcription library. Name comes from PARAKEET_LIBRARY, defaulting to libparakeet.dylib (macOS) or libparakeet.so (Linux); RTLD_NOW forces immediate symbol resolution so undefined parakeet_capi_* symbols also produce this error.","triggerScenarios":"Backend started before the C++ library is built/installed; PARAKEET_LIBRARY set to a non-library or truncated file; the .so cannot find its own runtime dependencies; architecture mismatch between the Go process and the library.","commonSituations":"Fresh deployments that ship the Go binary but not the artifacts/ directory containing the .so; upgrading the Go backend without rebuilding the native lib (ABI drift often shows as dlopen failure when soname deps change); containers missing CUDA/ONNX runtime libs.","solutions":["Verify the library exists and is a valid ELF/Mach-O of the right architecture (file libparakeet.so)","Build the native parakeet library and place it where the backend runs, or set PARAKEET_LIBRARY to its absolute path","Resolve missing dependencies shown by ldd libparakeet.so / otool -L libparakeet.dylib","If using the fallback variant path, make sure the variants/fallback directory layout is intact"],"exampleFix":"# before\n./parakeet-cpp  # panic: parakeet-cpp: dlopen \"libparakeet.so\": ...\n# after\nPARAKEET_LIBRARY=/opt/localai/backends/libparakeet.so ./parakeet-cpp","handlingStrategy":"validation","validationCode":"lib := os.Getenv(\"PARAKEET_LIBRARY\"); if lib == \"\" { lib = defaultLibName() }\nif _, err := os.Stat(lib); err != nil { log.Fatalf(\"parakeet-cpp: library %q missing: %v\", lib, err) }","typeGuard":"func libAvailable(path string) bool { _, err := os.Stat(path); return err == nil }","tryCatchPattern":null,"preventionTips":["Rebuild both Go backend and native lib together on upgrades","Preserve the variants/ directory layout when packaging","Stat the library in a prestart hook so failures are actionable"],"tags":["dlopen","native-library","go","backend","environment"],"backgroundTag":null,"analyzedSha":"44413a9d06bf5bc52ce088ba8ca74e5a2e8bee26","analyzedAt":"2026-08-15T10:13:50.291Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}