What causes "Lookup Server hostname failed" in netchx/netch?

Verify server.Hostname resolves from the same machine: nslookup in a shell.

netchx/netch · error · MessageException

Lookup Server hostname failed

Error message

Lookup Server hostname failed

What it means

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.

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.

Defensive patterns

Strategy: validation

Validate before calling

// Pre-resolve the hostname before touching the network stack.
var ip = await DnsUtils.LookupAsync(server.Hostname);
if (ip == null)
    throw new MessageException($"Cannot resolve '{server.Hostname}'. Check DNS/network and the server config.");

Try / catch

try { await MainController.StartAsync(server, mode); }
catch (MessageException ex) when (ex.Message.Contains("Lookup Server hostname failed"))
{
    NotifyUser($"Could not resolve host '{server.Hostname}'. Verify network/DNS or fix the server address.");
    return;
}

Prevention

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.

When it happens

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

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

Related errors

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

Appendix: source

Thrown at Netch/Controllers/MainController.cs:33

    public static Server? Server { get; private set; }

    public static Mode? Mode { get; private set; }

    public static IServerController? ServerController { get; private set; }

    public static IModeController? ModeController { get; private set; }

    private static readonly AsyncSemaphore Lock = new(1);

    public static async Task StartAsync(Server server, Mode mode)
    {
        using var releaser = await Lock.EnterAsync();

        Log.Information("Start MainController: {Server} {Mode}", $"{server.Type}", $"[{(int)mode.Type}]{mode.i18NRemark}");

        if (await DnsUtils.LookupAsync(server.Hostname) == null)
            throw new MessageException(i18N.Translate("Lookup Server hostname failed"));

        // TODO Disable NAT Type Test setting
        // cache STUN Server ip to prevent "Wrong STUN Server"
        DnsUtils.LookupAsync(Global.Settings.STUN_Server).Forget();

        Server = server;
        Mode = mode;

        await Task.WhenAll(Task.Run(NativeMethods.RefreshDNSCache), Task.Run(Firewall.AddNetchFwRules));

        try
        {
            ModeController = ModeService.GetModeControllerByType(mode.Type, out var modePort, out var portName);

            if (modePort != null)
                TryReleaseTcpPort((ushort)modePort, portName);

            if (Server is Socks5Server socks5 && (!socks5.Auth() || ModeController.Features.HasFlag(ModeFeature.SupportSocks5Auth)))

View on GitHub (pinned to 9d99eb1c5a)