{"record":{"id":"6c753d6265618055","repo":"netbirdio/netbird","slug":"couldn-t-find-module-path-for-s-error-v","errorCode":null,"errorMessage":"couldn't find module path for %s, error: %v","messagePattern":"couldn't find module path for (.+?), error: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"client/iface/device/kernel_module_linux.go","lineNumber":131,"sourceCode":"\t// for the existence of the wireguard module without actually\n\t// creating a link.\n\t//\n\t// As a side-effect, this will also let the kernel lazy-load\n\t// the wireguard module.\n\tlink.attrs.MTU = math.MaxInt\n\n\terr := netlink.LinkAdd(link)\n\n\treturn errors.Is(err, syscall.EINVAL)\n}\n\nfunc tryToLoadModule(moduleName string) (bool, error) {\n\tif isModuleEnabled(moduleName) {\n\t\treturn true, nil\n\t}\n\tmodulePath, err := getModulePath(moduleName)\n\tif err != nil {\n\t\treturn false, fmt.Errorf(\"couldn't find module path for %s, error: %v\", moduleName, err)\n\t}\n\tif modulePath == \"\" {\n\t\treturn false, nil\n\t}\n\n\tlog.Infof(\"trying to load %s module\", moduleName)\n\n\terr = loadModuleWithDependencies(moduleName, modulePath)\n\tif err != nil {\n\t\treturn false, fmt.Errorf(\"couldn't load %s module, error: %v\", moduleName, err)\n\t}\n\treturn true, nil\n}\n\nfunc isModuleEnabled(name string) bool {\n\tbuiltin, builtinErr := isBuiltinModule(name)\n\tstate, statusErr := moduleStatus(name)\n\treturn (builtinErr == nil && builtin) || (statusErr == nil && state >= loading)","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/iface/device/kernel_module_linux.go#L113-L149","documentation":"tryToLoadModule() failed to determine the on-disk path of the wireguard (or tun) kernel module. getModulePath walks moduleRoot, i.e. /lib/modules/$(uname -r) computed at package init, matching module file names; the wrapped %v is the filesystem error from that walk. Note a module simply absent yields an empty path and returns (false, nil), so this message means walking the module tree itself errored, which is rare because per-entry errors are skipped. WireGuardModuleIsLoaded logs it and returns false, so the agent falls back to userspace wireguard.","triggerScenarios":"Filesystem-level failures while walking /lib/modules/<kernel-release> (permission or I/O errors); partial or broken bind-mounts of the module directory in containers; odd layouts after kernel upgrades.","commonSituations":"Hardened/minimal systems with restricted /lib/modules, containers with incomplete module trees, module directory left inconsistent by an interrupted kernel package update.","solutions":["Verify /lib/modules/$(uname -r) exists, is readable, and matches the running kernel","Reinstall the matching kernel modules package and run depmod -a","If kernel WireGuard is unavailable, explicitly accept userspace mode by setting NB_WG_KERNEL_DISABLED=true","Read the wrapped %v to find the exact fs error and fix that path"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// verify the module tree exists and matches the running kernel\nroot := filepath.Join(\"/lib/modules\", kernelRelease())\nif info, err := os.Stat(root); err != nil || !info.IsDir() {\n    log.Warn(\"kernel module tree missing; agent will use userspace wireguard\")\n}","typeGuard":null,"tryCatchPattern":"if !device.WireGuardModuleIsLoaded() {\n    // kernel wireguard unavailable (module lookup/load failed);\n    // proceed in userspace mode instead of failing bring-up\n}","preventionTips":["Install kernel module packages matching the running kernel and run depmod after updates","Mount /lib/modules fully (or not at all) in containers","Accept and monitor the userspace fallback path as a deliberate degradation"],"tags":["linux","kernel-module","wireguard","filesystem","fallback"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}