netchx/netch · error · MessageException

tun2socks start failed.

Error message

tun2socks start failed.

What it means

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.

Source

Thrown at Netch/Controllers/TUNController.cs:107

            #endregion

            #region DNS

            if (_tunConfig.UseCustomDNS)
            {
                Dial(NameList.TYPE_DNSADDR, DnsUtils.AppendPort(_tunConfig.DNS));
            }
            else
            {
                await _aioDnsController.StartAsync();
                Dial(NameList.TYPE_DNSADDR, $"127.0.0.1:{Global.Settings.AioDNS.ListenPort}");
            }

            #endregion

            if (!Init())
                throw new MessageException("tun2socks start failed.");

            var tunIndex = (int)RouteHelper.ConvertLuidToIndex(tun_luid());
            _tun = NetRoute.TemplateBuilder(_tunConfig.Gateway, tunIndex);

            RouteHelper.CreateUnicastIP(AddressFamily.InterNetwork,
                _tunConfig.Address,
                (byte)Utils.Utils.SubnetToCidr(_tunConfig.Netmask),
                (ulong)tunIndex);

            SetupRouteTable();
        }

        public async Task StopAsync()
        {
            var tasks = new[]
            {
                FreeAsync(),
                Task.Run(ClearRouteTable),

View on GitHub (pinned to 9d99eb1c5a)

Solutions

1. Run Netch as administrator (TUN/route operations require elevation).
2. Confirm bin\wintun.dll exists and that %SystemRoot%\System32\wintun.dll was created (CheckDriver logs the copy and hashes).
3. Check TUNTAP settings: address, netmask, gateway must be a consistent private subnet; MTU 1500 default.
4. Remove any leftover 'netch' adapter from a previous run (Device Manager or `netsh interface show interface`).
5. Read the tun2socks Verbose logs for which Dial/init step failed; reinstall Netch to restore tun2socks.bin if missing.

// Pre-flight checks before tun_init.
if (!HasAdminRights())
    throw new MessageException("TUN mode requires administrator privileges.");
if (!File.Exists(Path.Combine(Global.NetchDir, Constants.WintunDllFile)))
    throw new MessageException($"{Constants.WintunDllFile} missing from bin\\");
var tun = Global.Settings.TUNTAP;
if (!IPAddress.TryParse(tun.Address, out _) || !IPAddress.TryParse(tun.Gateway, out _))
    throw new MessageException("TUN Address/Gateway is not a valid IP");
if (Utils.Utils.SubnetToCidr(tun.Netmask) < 0 || Utils.Utils.SubnetToCidr(tun.Netmask) > 32)
    throw new MessageException("TUN Netmask is invalid");

try { await tunController.StartAsync(server, mode); }
catch (MessageException ex) when (ex.Message == "tun2socks start failed.")
{
    Log.Error("tun_init returned false; wintun copied={Copied}", File.Exists($"{Environment.SystemDirectory}\\wintun.dll"));
    throw;
}

When it happens

Trigger: 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'.

Common situations: 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.

Related errors

• Redirector start failed.
• AioDNS start failed.
• bin\{mainFile} file not found!
• {Name} 控制器启动失败
• {e.Message} Missing File or runtime components

AI-assisted analysis of netchx/netch@9d99eb1c5a (2026-08-13). Data as JSON: /api/errors/4b82651def474253. Report an issue: GitHub.