{"record":{"id":"f6b93f09e090141c","repo":"slackhq/nebula","slug":"create-tun-device-failed-w","errorCode":null,"errorMessage":"create TUN device failed: %w","messagePattern":"create TUN device failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"overlay/tun_windows.go","lineNumber":101,"sourceCode":"\t\tl:               l,\n\t}\n\n\terr = t.reload(c, true)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tvar tunDevice wintun.Device\n\ttunDevice, err = wintun.CreateTUNWithRequestedGUID(deviceName, guid, t.MTU)\n\tif err != nil {\n\t\t// Windows 10 has an issue with unclean shutdowns not fully cleaning up the wintun device.\n\t\t// Trying a second time resolves the issue.\n\t\tl.Debug(\"Failed to create wintun device, retrying\", \"error\", err)\n\t\ttunDevice, err = wintun.CreateTUNWithRequestedGUID(deviceName, guid, t.MTU)\n\t\tif err != nil {\n\t\t\treturn nil, &NameError{\n\t\t\t\tName:       deviceName,\n\t\t\t\tUnderlying: fmt.Errorf(\"create TUN device failed: %w\", err),\n\t\t\t}\n\t\t}\n\t}\n\tt.tun = tunDevice.(*wintun.NativeTun)\n\n\tc.RegisterReloadCallback(func(c *config.C) {\n\t\terr := t.reload(c, false)\n\t\tif err != nil {\n\t\t\tutil.LogWithContextIfNeeded(\"failed to reload tun device\", err, t.l)\n\t\t}\n\t})\n\n\treturn t, nil\n}\n\nfunc (t *winTun) reload(c *config.C, initial bool) error {\n\tchange, routes, err := getAllRoutesFromConfig(c, t.vpnNetworks, initial)\n\tif err != nil {","sourceCodeStart":83,"sourceCodeEnd":119,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_windows.go#L83-L119","documentation":"newTun failed twice to create the wintun TUN device via wintun.CreateTUNWithRequestedGUID, even after one retry. The error is wrapped in a NameError carrying the requested deviceName. This library throws it because the underlying wintun driver refused to create the interface (driver missing, name conflict, or permission problem).","triggerScenarios":"Calling newTun on Windows when the wintun.dll driver is missing/not loadable, the requested interface name is invalid or already in use, the process lacks administrator privileges, or the MTU is invalid — in both initial attempt and the single retry.","commonSituations":"Running nebula without elevated privileges; missing wintun.dll in PATH or alongside the binary; stale/orphaned wintun adapter from a previous crash; outdated wintun driver conflicting with WireGuard installs.","solutions":["Run the process as Administrator","Ensure a compatible wintun.dll is present next to the binary or in PATH","Delete stale wintun adapters (Device Manager > network adapters, or 'netcfg -d' as last resort)","Update wintun.dll/driver to the latest release","Check the tun.device name config for invalid characters or a conflicting existing adapter"],"exampleFix":"// before\nsudo nebula -config config.yml\n// after (elevated PowerShell)\nStart-Process nebula -ArgumentList '-config config.yml' -Verb RunAs","handlingStrategy":"try-catch","validationCode":"// Windows, before starting: require elevation and wintun.dll presence\nif !windows.GetCurrentProcessToken().IsElevated() {\n    return errors.New(\"nebula requires administrator privileges on Windows\")\n}\nif _, err := os.Stat(filepath.Join(exeDir, \"wintun.dll\")); err != nil {\n    return errors.New(\"wintun.dll not found next to the binary\")\n}","typeGuard":"var nameErr *overlay.NameError\nif errors.As(err, &nameErr) {\n    log.Printf(\"TUN creation failed for device %q: %v\", nameErr.Name, nameErr.Underlying)\n}","tryCatchPattern":"tun, err := overlay.NewTunFromConf(...)\nif err != nil {\n    var ne *overlay.NameError\n    if errors.As(err, &ne) {\n        log.Fatalf(\"create TUN %s failed: %v\", ne.Name, ne.Underlying)\n    }\n    return err\n}","preventionTips":["Always run nebula elevated on Windows","Ship and pin wintun.dll with the binary","Name the TUN device uniquely to avoid collisions","Clean up stale wintun adapters after crashes","Keep wintun driver current"],"tags":["windows","tun","wintun","network-interface"],"backgroundTag":"tun-device-creation-failed","analyzedSha":"dd8f660c0ac37903ec4080ca4d3c861ba9342ceb","analyzedAt":"2026-09-03T11:13:55.444Z","contentChangedAt":"2026-09-03T11:13:55.444Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}