{"record":{"id":"4b82651def474253","repo":"netchx/netch","slug":"tun2socks-start-failed","errorCode":null,"errorMessage":"tun2socks start failed.","messagePattern":"tun2socks start failed\\.","errorType":"exception","errorClass":"MessageException","httpStatus":null,"severity":"error","filePath":"Netch/Controllers/TUNController.cs","lineNumber":107,"sourceCode":"\n            #endregion\n\n            #region DNS\n\n            if (_tunConfig.UseCustomDNS)\n            {\n                Dial(NameList.TYPE_DNSADDR, DnsUtils.AppendPort(_tunConfig.DNS));\n            }\n            else\n            {\n                await _aioDnsController.StartAsync();\n                Dial(NameList.TYPE_DNSADDR, $\"127.0.0.1:{Global.Settings.AioDNS.ListenPort}\");\n            }\n\n            #endregion\n\n            if (!Init())\n                throw new MessageException(\"tun2socks start failed.\");\n\n            var tunIndex = (int)RouteHelper.ConvertLuidToIndex(tun_luid());\n            _tun = NetRoute.TemplateBuilder(_tunConfig.Gateway, tunIndex);\n\n            RouteHelper.CreateUnicastIP(AddressFamily.InterNetwork,\n                _tunConfig.Address,\n                (byte)Utils.Utils.SubnetToCidr(_tunConfig.Netmask),\n                (ulong)tunIndex);\n\n            SetupRouteTable();\n        }\n\n        public async Task StopAsync()\n        {\n            var tasks = new[]\n            {\n                FreeAsync(),\n                Task.Run(ClearRouteTable),","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/netchx/netch/blob/9d99eb1c5a2acbf2a34f2600f94242601019a300/Netch/Controllers/TUNController.cs#L89-L125","documentation":"Thrown by TUNController.StartAsync when the native tun2socks engine's Init() (tun_init in tun2socks.bin) returned false. By this point the wintun adapter was awaited, server/DNS Dial values were set, and the final tun_init failed. tun_init creates/configures the TUN adapter and starts the socks5-tun pipeline, so failure points at adapter creation, routing, or config.","triggerScenarios":"wintun.dll missing or wrong version in System32 (CheckDriver copies it); TUNConfig address/gateway/netmask/MTU invalid or conflicting; the wintun adapter failed to register within the 20x300ms wait; not running as admin; tun2socks.bin missing/corrupt; another VPN's TUN adapter already uses the name 'netch'.","commonSituations":"First TUN-mode use on a machine without wintun.dll deployed; user set a TUN address that overlaps an existing interface; antivirus blocks wintun; admin elevation missing; remnant adapter from a crashed previous run.","solutions":["Run Netch as administrator (TUN/route operations require elevation).","Confirm bin\\wintun.dll exists and that %SystemRoot%\\System32\\wintun.dll was created (CheckDriver logs the copy and hashes).","Check TUNTAP settings: address, netmask, gateway must be a consistent private subnet; MTU 1500 default.","Remove any leftover 'netch' adapter from a previous run (Device Manager or `netsh interface show interface`).","Read the tun2socks Verbose logs for which Dial/init step failed; reinstall Netch to restore tun2socks.bin if missing."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Pre-flight checks before tun_init.\nif (!HasAdminRights())\n    throw new MessageException(\"TUN mode requires administrator privileges.\");\nif (!File.Exists(Path.Combine(Global.NetchDir, Constants.WintunDllFile)))\n    throw new MessageException($\"{Constants.WintunDllFile} missing from bin\\\\\");\nvar tun = Global.Settings.TUNTAP;\nif (!IPAddress.TryParse(tun.Address, out _) || !IPAddress.TryParse(tun.Gateway, out _))\n    throw new MessageException(\"TUN Address/Gateway is not a valid IP\");\nif (Utils.Utils.SubnetToCidr(tun.Netmask) < 0 || Utils.Utils.SubnetToCidr(tun.Netmask) > 32)\n    throw new MessageException(\"TUN Netmask is invalid\");","typeGuard":null,"tryCatchPattern":"try { await tunController.StartAsync(server, mode); }\ncatch (MessageException ex) when (ex.Message == \"tun2socks start failed.\")\n{\n    Log.Error(\"tun_init returned false; wintun copied={Copied}\", File.Exists($\"{Environment.SystemDirectory}\\\\wintun.dll\"));\n    throw;\n}","preventionTips":["Run Netch as administrator for TUN mode.","Confirm wintun.dll is deployed to System32 (CheckDriver logs the copy and hashes).","Use a unique private subnet for TUN address/gateway that overlaps no existing interface.","Remove leftover 'netch' adapters after a crash before restarting."],"tags":["tun","driver","native-interop","startup"],"backgroundTag":null,"analyzedSha":"9d99eb1c5a2acbf2a34f2600f94242601019a300","analyzedAt":"2026-08-13T14:12:19.105Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}