{"record":{"id":"20415f129708c4bb","repo":"netbirdio/netbird","slug":"error-creating-tun-device-s-20415f","errorCode":null,"errorMessage":"error creating tun device: %s","messagePattern":"error creating tun device: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"client/iface/device/device_windows.go","lineNumber":65,"sourceCode":"\nfunc getGUID() (windows.GUID, error) {\n\tguidString := defaultWindowsGUIDSTring\n\tif CustomWindowsGUIDString != \"\" {\n\t\tguidString = CustomWindowsGUIDString\n\t}\n\treturn windows.GUIDFromString(guidString)\n}\n\nfunc (t *TunDevice) Create() (WGConfigurer, error) {\n\tguid, err := getGUID()\n\tif err != nil {\n\t\tlog.Errorf(\"failed to get GUID: %s\", err)\n\t\treturn nil, err\n\t}\n\tlog.Info(\"create tun interface\")\n\ttunDevice, err := tun.CreateTUNWithRequestedGUID(t.name, &guid, int(t.mtu))\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error creating tun device: %s\", err)\n\t}\n\tt.nativeTunDevice = tunDevice.(*tun.NativeTun)\n\tt.filteredDevice = newDeviceFilter(tunDevice)\n\n\t// We need to create a wireguard-go device and listen to configuration requests\n\tt.device = device.NewDevice(\n\t\tt.filteredDevice,\n\t\tt.iceBind,\n\t\tdevice.NewLogger(wgLogLevel(), \"[netbird] \"),\n\t)\n\n\tluid := winipcfg.LUID(t.nativeTunDevice.LUID())\n\n\tnbiface, err := luid.IPInterface(windows.AF_INET)\n\tif err != nil {\n\t\tt.device.Close()\n\t\treturn nil, fmt.Errorf(\"got error when getting ip interface %s\", err)\n\t}","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/iface/device/device_windows.go#L47-L83","documentation":"Windows Create() failed at tun.CreateTUNWithRequestedGUID, which creates the wintun adapter with the requested name, GUID and MTU via the wintun driver (wintun.dll loaded by wireguard-go's tun package). The GUID itself was already resolved by getGUID earlier; failing there returns a different error, so this wrap is specifically adapter creation.","triggerScenarios":"wintun.dll missing or wrong architecture, unsupported Windows build, adapter name conflict, driver resource exhaustion, daemon not running elevated.","commonSituations":"Fresh systems without the driver, antivirus quarantining wintun.dll, wireguard-go/wintun version mismatches after upgrades, running the daemon as a non-elevated user.","solutions":["Run the NetBird Windows service as LocalSystem/administrator","Reinstall the client so the bundled wintun.dll is restored (AV may have removed it)","Remove stale adapters with the same name and retry creation","Confirm the Windows version is supported by the bundled wintun release"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"var token windows.Token\nif err := windows.OpenProcessToken(windows.CurrentProcess(), windows.TOKEN_QUERY, &token); err == nil {\n    if elev, _ := token.IsElevated(); !elev {\n        log.Warn(\"wintun adapter creation requires an elevated service\")\n    }\n}","typeGuard":null,"tryCatchPattern":"if _, err := dev.Create(); err != nil {\n    if strings.Contains(err.Error(), \"error creating tun device\") {\n        // driver problem: verify wintun.dll presence, AV exclusions, and elevation; reinstall client\n    }\n    return err\n}","preventionTips":["Run the Windows service as LocalSystem","Keep the client's bundled wintun.dll intact and excluded from AV quarantine","Clean stale adapters with conflicting names before bring-up"],"tags":["windows","wintun","adapter","driver","permissions"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}