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.

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)

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.