What causes "The {0} port is reserved by system." in netchx/netch?

List reserved ranges: `netsh int ipv4 show excludedportrange protocol=tcp` (and udp).

netchx/netch · error · MessageException

The {0} port is reserved by system.

Error message

The {0} port is reserved by system.

What it means

Thrown by MainController.PortCheck when PortHelper.CheckPort raises PortReservedException — the port falls inside a Windows excluded port range parsed from `netsh int ipv4 show excludedportrange`. These ranges are reserved (typically by Hyper-V/WSL/Docker/Windows update) and cannot be bound even when no listener is active.

Source

Thrown at Netch/Controllers/MainController.cs:146

        }

        ServerController = null;
        ModeController = null;
    }

    public static void PortCheck(ushort port, string portName, PortType portType = PortType.Both)
    {
        try
        {
            PortHelper.CheckPort(port, portType);
        }
        catch (PortInUseException)
        {
            throw new MessageException(i18N.TranslateFormat("The {0} port is in use.", $"{portName} ({port})"));
        }
        catch (PortReservedException)
        {
            throw new MessageException(i18N.TranslateFormat("The {0} port is reserved by system.", $"{portName} ({port})"));
        }
    }

    public static void TryReleaseTcpPort(ushort port, string portName)
    {
        foreach (var p in PortHelper.GetProcessByUsedTcpPort(port))
        {
            var fileName = p.MainModule?.FileName;
            if (fileName == null)
                continue;

            if (fileName.StartsWith(Global.NetchDir))
            {
                p.Kill();
                p.WaitForExit();
            }
            else
            {

View on GitHub (pinned to 9d99eb1c5a)

Solutions

List reserved ranges: `netsh int ipv4 show excludedportrange protocol=tcp` (and udp).
Change the configured port to one outside every listed range (low ports like 1080/1086 usually safe).
Optionally shrink Hyper-V's dynamic range: `netsh int ipv4 set dynamicport tcp start=49152 num=16384` after restarting Hyper-V compute service.
Reboot after changing reservations so the excluded list refreshes.

Defensive patterns

Strategy: validation

Validate before calling

// Reject ports inside Windows excluded ranges before binding.
// PortHelper.CheckPort already throws PortReservedException; call it on the settings page:
try { PortHelper.CheckPort(port, PortType.Both); }
catch (PortReservedException) { /* mark port invalid in the UI */ }

Try / catch

try { MainController.PortCheck(port, portName); }
catch (MessageException ex) when (ex.Message.Contains("reserved by system"))
{
    SuggestPortsOutsideExcludedRanges(portName);
}

Prevention

Pick ports below the Windows dynamic range (e.g. 1080) to dodge Hyper-V/WSL reservations.
Cache the `netsh int ipv4 show excludedportrange` list at startup and reject reserved ports in the UI.
After installing Hyper-V/Docker/WSL, re-check your chosen port.
Reboot after changing dynamic port ranges so the excluded list refreshes.

When it happens

Trigger: Configured Socks5/mode/AioDNS port lies within a TCP or UDP excluded range populated by Hyper-V dynamic port reservations; the reserved-range list changed after a reboot or after starting Docker/WSL.

Common situations: Hyper-V/WSL2 installed, which reserves large swaths of dynamic ports; Docker Desktop reserving ports; user picked a port in the 50000+ dynamic range that Windows handed to Hyper-V.

Related errors

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