{"record":{"id":"6fdb00c3fafc65a0","repo":"henrygd/beszel","slug":"failed-to-load-s-w","errorCode":null,"errorMessage":"failed to load %s: %w","messagePattern":"failed to load (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent/gpu_nvml.go","lineNumber":82,"sourceCode":"\tnvmlDeviceGetPciInfo          func(device nvmlDevice, pci *nvmlPciInfo) nvmlReturn\n\tnvmlErrorString               func(result nvmlReturn) string\n)\n\ntype nvmlCollector struct {\n\tgm      *GPUManager\n\tlib     uintptr\n\tdevices []nvmlDevice\n\tbdfs    []string\n\tisV2    bool\n}\n\nfunc (c *nvmlCollector) init() error {\n\tslog.Debug(\"NVML: Initializing\")\n\tlibPath := getNVMLPath()\n\n\tlib, err := openLibrary(libPath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to load %s: %w\", libPath, err)\n\t}\n\tc.lib = lib\n\n\tpurego.RegisterLibFunc(&nvmlInit, lib, \"nvmlInit\")\n\tpurego.RegisterLibFunc(&nvmlShutdown, lib, \"nvmlShutdown\")\n\tpurego.RegisterLibFunc(&nvmlDeviceGetCount, lib, \"nvmlDeviceGetCount\")\n\tpurego.RegisterLibFunc(&nvmlDeviceGetHandleByIndex, lib, \"nvmlDeviceGetHandleByIndex\")\n\tpurego.RegisterLibFunc(&nvmlDeviceGetName, lib, \"nvmlDeviceGetName\")\n\t// Try to get v2 memory info, fallback to v1 if not available\n\tif hasSymbol(lib, \"nvmlDeviceGetMemoryInfo_v2\") {\n\t\tc.isV2 = true\n\t\tpurego.RegisterLibFunc(&nvmlDeviceGetMemoryInfo, lib, \"nvmlDeviceGetMemoryInfo_v2\")\n\t} else {\n\t\tpurego.RegisterLibFunc(&nvmlDeviceGetMemoryInfo, lib, \"nvmlDeviceGetMemoryInfo\")\n\t}\n\tpurego.RegisterLibFunc(&nvmlDeviceGetUtilizationRates, lib, \"nvmlDeviceGetUtilizationRates\")\n\tpurego.RegisterLibFunc(&nvmlDeviceGetTemperature, lib, \"nvmlDeviceGetTemperature\")\n\tpurego.RegisterLibFunc(&nvmlDeviceGetPowerUsage, lib, \"nvmlDeviceGetPowerUsage\")","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/henrygd/beszel/blob/b38fb7dafa60812cc22e6a84ce313e94f1ce0a32/agent/gpu_nvml.go#L64-L100","documentation":"The NVML collector's init fails when the NVIDIA Management Library shared object cannot be opened via purego/dlopen. This is thrown before any NVML calls are made, so it indicates a missing or unloadable libnvidia-ml library rather than an NVIDIA API error.","triggerScenarios":"startNvmlCollector constructs an nvmlCollector and calls init(); getNVMLPath() returns a path and openLibrary(libPath) fails — library absent, wrong architecture, or unresolved symbols.","commonSituations":"NVIDIA driver not installed; headless/driverless setups; musl-based distros (Alpine) lacking glibc compatibility for the driver libs; container without NVIDIA runtime so no driver libs mounted; agent built for a different arch than the host.","solutions":["Install the NVIDIA driver so libnvidia-ml.so exists (nvidia-smi should work on the host).","In containers, run with the NVIDIA container runtime / --gpus all so driver libraries are injected.","Locate the lib and make it discoverable: export LD_LIBRARY_PATH=$(dirname $(ldconfig -p | grep libnvidia-ml | awk '{print $NF}')).","Check the path returned by getNVMLPath and override if a different lib location is needed.","On Alpine/musl, install glibc-compat or use a glibc-based image."],"exampleFix":"// before (docker, no GPU runtime)\ndocker run beszel/agent\n// after\ndocker run --gpus all beszel/agent","handlingStrategy":"validation","validationCode":"// before deploying, confirm NVML is loadable:\nldconfig -p | grep libnvidia-ml || echo 'NVML missing'\nnvidia-smi -L || echo 'driver unusable'","typeGuard":null,"tryCatchPattern":"if err := c.init(); err != nil {\n    if strings.Contains(err.Error(), \"failed to load\") {\n        slog.Warn(\"NVML library unavailable; skipping NVML collector\", \"err\", err)\n        return nil\n    }\n    return err\n}","preventionTips":["Install NVIDIA drivers in every image that runs the agent","Use --gpus all / NVIDIA container runtime for containerized agents","Match container arch to host arch (glibc driver libs)","Add a startup check (ldconfig -p | grep libnvidia-ml) to deployment health gates"],"tags":["gpu","nvidia","nvml","dynamic-library"],"backgroundTag":"shared-library-load-failure","analyzedSha":"b38fb7dafa60812cc22e6a84ce313e94f1ce0a32","analyzedAt":"2026-08-31T15:10:10.149Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}