{"record":{"id":"6579562036402d87","repo":"netchx/netch","slug":"failed-to-copy-wintun-dll-to-system-directory-e","errorCode":null,"errorMessage":"Failed to copy wintun.dll to system directory: {e.Message}","messagePattern":"Failed to copy wintun\\.dll to system directory: (.+?)","errorType":"exception","errorClass":"MessageException","httpStatus":null,"severity":"error","filePath":"Netch/Controllers/TUNController.cs","lineNumber":152,"sourceCode":"            string binDriver = Path.Combine(Global.NetchDir, Constants.WintunDllFile);\n            string sysDriver = $@\"{Environment.SystemDirectory}\\wintun.dll\";\n\n            var binHash = Utils.Utils.Sha256CheckSumAsync(binDriver).Result;\n            var sysHash = Utils.Utils.Sha256CheckSumAsync(sysDriver).Result;\n            Log.Information(\"Built-in  wintun.dll Hash: {Hash}\", binHash);\n            Log.Information(\"Installed wintun.dll Hash: {Hash}\", sysHash);\n            if (binHash == sysHash)\n                return;\n\n            try\n            {\n                Log.Information(\"Copy wintun.dll to System Directory\");\n                File.Copy(binDriver, sysDriver, true);\n            }\n            catch (Exception e)\n            {\n                Log.Error(e, \"Copy wintun.dll failed\");\n                throw new MessageException($\"Failed to copy wintun.dll to system directory: {e.Message}\");\n            }\n        }\n\n        #region Route\n\n        private void SetupRouteTable()\n        {\n            Global.MainForm.StatusText(i18N.Translate(\"Setup Route Table Rule\"));\n\n            var tunNetworkInterface = NetworkInterfaceUtils.Get(_tun.InterfaceIndex);\n            // Server Address\n            if (_serverRemoteAddress != null)\n                RouteUtils.CreateRoute(_outbound.FillTemplate(_serverRemoteAddress.ToString(), 32));\n\n            // Global Bypass IPs\n            RouteUtils.CreateRouteFill(_outbound, _tunConfig.BypassIPs);\n\n            // rule","sourceCodeStart":134,"sourceCodeEnd":170,"githubUrl":"https://github.com/netchx/netch/blob/9d99eb1c5a2acbf2a34f2600f94242601019a300/Netch/Controllers/TUNController.cs#L134-L170","documentation":"Thrown by TUNController.CheckDriver when File.Copy(bin\\wintun.dll -> %SystemRoot%\\System32\\wintun.dll, overwrite:true) raised an exception. The hashes differed (so a copy was needed) but the copy itself failed; e.Message is appended. This blocks TUN mode because tun_init needs the system-resident wintun.dll.","triggerScenarios":"Netch not running elevated so it cannot write System32\\wintun.dll; an existing wintun.dll is loaded/locked by a running TUN session or another VPN; antivirus blocks the write; disk full; Windows Resource Protection or Controlled Folder Access blocking System32 writes.","commonSituations":"User didn't run as admin; another app (WireGuard, another Netch instance, a VPN client) holds wintun.dll loaded; Defender tamper protection blocks it.","solutions":["Relaunch Netch as administrator.","Close any other VPN/TUN client that may have wintun.dll loaded, then retry.","Stop the current Netch TUN mode fully (StopAsync frees tun2socks which unloads wintun) before retrying Start.","Add an antivirus/tamper-protection exclusion for the Netch directory and System32\\wintun.dll.","Manually copy bin\\wintun.dll to %SystemRoot%\\System32\\wintun.dll from an elevated shell if the in-app copy keeps failing."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Only attempt the copy when elevated and the target isn't locked.\nif (!HasAdminRights())\n    throw new MessageException(\"Updating wintun.dll requires administrator privileges.\");\nstring sys = $\"{Environment.SystemDirectory}\\\\wintun.dll\";\nif (File.Exists(sys))\n    try { File.OpenWrite(sys).Dispose(); } catch { /* locked */ throw new MessageException(\"wintun.dll is locked; stop TUN mode first.\"); }","typeGuard":null,"tryCatchPattern":"try { /* TUNController.CheckDriver copy */ }\ncatch (MessageException ex) when (ex.Message.StartsWith(\"Failed to copy wintun.dll\"))\n{\n    // ex.Message has the inner exception; most common fix is elevation or stopping other VPNs.\n    SuggestRunAsAdminOrCloseOtherVPN(ex.Message);\n}","preventionTips":["Run Netch elevated whenever wintun.dll needs updating.","Stop the current TUN session (StopAsync frees tun2socks) before retrying Start so wintun.dll isn't loaded.","Close other VPN clients that load wintun.dll.","Add an AV exclusion for System32\\wintun.dll."],"tags":["tun","driver","file-system","permissions"],"backgroundTag":null,"analyzedSha":"9d99eb1c5a2acbf2a34f2600f94242601019a300","analyzedAt":"2026-08-13T14:12:19.105Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}