netchx/netch · error · MessageException

AioDNS start failed.

Error message

AioDNS start failed.

What it means

Thrown by DNSController.StartAsync after the native AioDNS engine's InitAsync() (P/Invoke aiodns_init in aiodns.bin) returned false. The controller first Dials listen address, China DNS, Other DNS, and the rule file path into the engine, then asks it to initialize; a false return means the engine rejected the configuration or could not bind. The message itself gives no detail, so the real cause is only visible in the Verbose Dial logs or the engine's own output.

Source

Thrown at Netch/Controllers/DNSController.cs:23

namespace Netch.Controllers;

public class DNSController : IController
{
    public string Name => "DNS Service";

    public async Task StartAsync()
    {
        var aioDnsConfig = Global.Settings.AioDNS;

        Dial(NameList.TYPE_REST, "");
        Dial(NameList.TYPE_LIST, Path.GetFullPath(Constants.AioDnsRuleFile));
        // TODO remove ListenPort setting
        Dial(NameList.TYPE_LISN, $"127.0.0.1:{aioDnsConfig.ListenPort}");
        Dial(NameList.TYPE_CDNS, $"{aioDnsConfig.ChinaDNS}");
        Dial(NameList.TYPE_ODNS, $"{aioDnsConfig.OtherDNS}");

        if (!await InitAsync())
            throw new MessageException("AioDNS start failed.");
    }

    public Task StopAsync()
    {
        return FreeAsync();
    }
}

View on GitHub (pinned to 9d99eb1c5a)

Solutions

1. Check logging\AioDNS or the Verbose logs for the exact Dial value that broke init, and the aiodns_init return path.
2. Change Global.Settings.AioDNS.ListenPort to a free port (avoid the Windows reserved range from `netsh int ipv4 show excludedportrange tcp`).
3. Verify bin\aiodns.conf exists under NetchDir; restore it from a clean release if missing.
4. Confirm ChinaDNS and OtherDNS are valid DNS URIs/hosts; defaults live in Constants.DefaultPrimaryDNS.
5. Reinstall Netch to restore aiodns.bin if it was removed by antivirus.

// Before calling _aioDnsController.StartAsync(), verify the inputs InitAsync needs.
var cfg = Global.Settings.AioDNS;
if (cfg.ListenPort == 0)
    throw new InvalidOperationException("AioDNS ListenPort is not set");
MainController.PortCheck(cfg.ListenPort, "AioDNS", PortType.UDP);
if (!File.Exists(Path.GetFullPath(Constants.AioDnsRuleFile)))
    throw new InvalidOperationException($"{Constants.AioDnsRuleFile} missing");
if (File.Exists(Path.Combine(Global.NetchDir, "bin", "aiodns.bin")) == false)
    throw new InvalidOperationException("aiodns.bin missing from bin\\");

try { await _aioDnsController.StartAsync(); }
catch (MessageException ex) when (ex.Message == "AioDNS start failed.")
{
    Log.Error(ex, "AioDNS init returned false; see Dial logs for the bad value");
    throw;
}

When it happens

Trigger: AioDNS ListenPort (Global.Settings.AioDNS.ListenPort) is already bound by another process; the rule file bin\aiodns.conf (Constants.AioDnsRuleFile) is missing so TYPE_LIST Dial points at a non-existent path; ChinaDNS/OtherDNS values are malformed; aiodns.bin native binary is missing/corrupt/wrong architecture so aiodns_init throws or returns false.

Common situations: Two Netch instances configured to the same AioDNS listen port; user edited settings to a port in the Windows excluded range; fresh install where bin\aiodns.conf was not shipped; antivirus quarantined aiodns.bin; 32-bit bin on 64-bit OS.

Related errors

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

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