{"record":{"id":"0ad4a5c6b722218f","repo":"slackhq/nebula","slug":"can-not-load-the-wintun-driver-w","errorCode":null,"errorMessage":"can not load the wintun driver: %w","messagePattern":"can not load the wintun driver: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"overlay/tun_windows.go","lineNumber":61,"sourceCode":"\tbypassWDF       bool\n\twdfBypass       closer\n\tl               *slog.Logger\n\n\ttun *wintun.NativeTun\n}\n\nfunc (t *winTun) Read(b []byte) (int, error) {\n\treturn t.tun.Read(b, 0)\n}\n\nfunc newTunFromFd(_ *config.C, _ *slog.Logger, _ int, _ []netip.Prefix) (Device, error) {\n\treturn nil, fmt.Errorf(\"newTunFromFd not supported in Windows\")\n}\n\nfunc newTun(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, _ bool) (*winTun, error) {\n\terr := checkWinTunExists()\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"can not load the wintun driver: %w\", err)\n\t}\n\n\tdeviceName := c.GetString(\"tun.dev\", \"\")\n\tguid, err := generateGUIDByDeviceName(deviceName)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"generate GUID failed: %w\", err)\n\t}\n\n\tcat, setCat, err := parseNetworkCategory(c.GetString(\"tun.network_category\", \"private\"))\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tt := &winTun{\n\t\tDevice:          deviceName,\n\t\tvpnNetworks:     vpnNetworks,\n\t\tMTU:             c.GetInt(\"tun.mtu\", DefaultMTU),\n\t\tguid:            *guid,","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_windows.go#L43-L79","documentation":"newTun on Windows requires the wintun.dll driver. checkWinTunExists() tries to load wintun.dll; when that fails, nebula wraps the cause as 'can not load the wintun driver'. Without wintun.dll the TUN device cannot be created and nebula cannot start.","triggerScenarios":"newTun calls checkWinTunExists() and LoadLibrary/finds no wintun.dll on the search path, an architecture-mismatched DLL (e.g. 32-bit DLL with 64-bit nebula), or a corrupted/incompatible wintun version.","commonSituations":"wintun.dll missing next to nebula.exe or in PATH; wrong architecture (x86 vs x64 vs arm64) DLL; antivirus quarantining wintun.dll; running from a stripped-down environment where the DLL wasn't bundled.","solutions":["Download the official wintun distribution and place the architecture-correct wintun.dll next to nebula.exe (or in PATH).","Verify DLL architecture matches the nebula binary (x64/x86/arm64).","Check antivirus/EDR quarantine logs and whitelist wintun.dll.","Ensure the wintun.dll version is one supported by your nebula release and not corrupted (re-download and compare checksums)."],"exampleFix":"// before\nnebula.exe in C:\\nebula\\ with no wintun.dll anywhere on PATH\n// after\nC:\\nebula\\\n  nebula.exe\n  wintun.dll   (amd64 build matching the nebula binary)","handlingStrategy":"validation","validationCode":"if _, err := os.Stat(filepath.Join(exeDir, \"wintun.dll\")); err != nil {\n\treturn errors.New(\"wintun.dll missing next to nebula.exe; install the official wintun distribution\")\n}","typeGuard":null,"tryCatchPattern":"tun, err := overlay.NewTun(cfg, logger, prefixes, false)\nif err != nil && strings.Contains(err.Error(), \"wintun driver\") {\n\t// surface install guidance: correct-arch wintun.dll beside the binary\n\treturn fmt.Errorf(\"install wintun: %w\", err)\n}","preventionTips":["Bundle the architecture-matching wintun.dll with every nebula deployment.","Verify checksums of wintun.dll after download.","Whitelist the DLL in antivirus/EDR policies.","Confirm DLL arch matches binary arch (x64/x86/arm64)."],"tags":["windows","tun","wintun","missing-dll"],"backgroundTag":"missing-driver-dll","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"}