{"record":{"id":"64102edbe0f73403","repo":"netchx/netch","slug":"lookup-server-hostname-failed","errorCode":null,"errorMessage":"Lookup Server hostname failed","messagePattern":"Lookup Server hostname failed","errorType":"exception","errorClass":"MessageException","httpStatus":null,"severity":"error","filePath":"Netch/Controllers/MainController.cs","lineNumber":33,"sourceCode":"\n    public static Server? Server { get; private set; }\n\n    public static Mode? Mode { get; private set; }\n\n    public static IServerController? ServerController { get; private set; }\n\n    public static IModeController? ModeController { get; private set; }\n\n    private static readonly AsyncSemaphore Lock = new(1);\n\n    public static async Task StartAsync(Server server, Mode mode)\n    {\n        using var releaser = await Lock.EnterAsync();\n\n        Log.Information(\"Start MainController: {Server} {Mode}\", $\"{server.Type}\", $\"[{(int)mode.Type}]{mode.i18NRemark}\");\n\n        if (await DnsUtils.LookupAsync(server.Hostname) == null)\n            throw new MessageException(i18N.Translate(\"Lookup Server hostname failed\"));\n\n        // TODO Disable NAT Type Test setting\n        // cache STUN Server ip to prevent \"Wrong STUN Server\"\n        DnsUtils.LookupAsync(Global.Settings.STUN_Server).Forget();\n\n        Server = server;\n        Mode = mode;\n\n        await Task.WhenAll(Task.Run(NativeMethods.RefreshDNSCache), Task.Run(Firewall.AddNetchFwRules));\n\n        try\n        {\n            ModeController = ModeService.GetModeControllerByType(mode.Type, out var modePort, out var portName);\n\n            if (modePort != null)\n                TryReleaseTcpPort((ushort)modePort, portName);\n\n            if (Server is Socks5Server socks5 && (!socks5.Auth() || ModeController.Features.HasFlag(ModeFeature.SupportSocks5Auth)))","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/netchx/netch/blob/9d99eb1c5a2acbf2a34f2600f94242601019a300/Netch/Controllers/MainController.cs#L15-L51","documentation":"Thrown by MainController.StartAsync when DnsUtils.LookupAsync(server.Hostname) returns null — the server's hostname could not be resolved to any IP within the 3-second DNS timeout. This is the first connectivity check before any controller is started, so it fails fast before touching the network stack.","triggerScenarios":"server.Hostname is blank or a typo; the local DNS resolver is unreachable or returns NXDOMAIN; system DNS is broken; captive portal intercepting DNS; the hostname is an IP string that failed to parse; no network interface is up.","commonSituations":"Offline or on a restricted network when clicking Start; copied a server config with a truncated host; DNS server in the user's environment blocked; recently changed networks and DNS cache/adapter is stale.","solutions":["Verify server.Hostname resolves from the same machine: nslookup <hostname> in a shell.","Check basic connectivity and that a DNS server is reachable.","Fix or re-enter the server's hostname in the edit form.","If on a captive portal, authenticate first, then retry Start.","Run NativeMethods.RefreshDNSCache equivalent (ipconfig /flushdns) and retry."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Pre-resolve the hostname before touching the network stack.\nvar ip = await DnsUtils.LookupAsync(server.Hostname);\nif (ip == null)\n    throw new MessageException($\"Cannot resolve '{server.Hostname}'. Check DNS/network and the server config.\");","typeGuard":null,"tryCatchPattern":"try { await MainController.StartAsync(server, mode); }\ncatch (MessageException ex) when (ex.Message.Contains(\"Lookup Server hostname failed\"))\n{\n    NotifyUser($\"Could not resolve host '{server.Hostname}'. Verify network/DNS or fix the server address.\");\n    return;\n}","preventionTips":["Validate the hostname is non-empty and well-formed before saving a server.","Run nslookup on the host before clicking Start if the network looks iffy.","Flush DNS (ipconfig /flushdns) when switching networks.","Resolve captive portals before starting the tunnel."],"tags":["dns","network","validation","startup"],"backgroundTag":null,"analyzedSha":"9d99eb1c5a2acbf2a34f2600f94242601019a300","analyzedAt":"2026-08-13T14:12:19.105Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}