microsoft/aspire · error · ArgumentOutOfRangeException

Port range start must be between

Error message

Port range start must be between {MinPort} and {MaxPort}.

What it means

Thrown by PortRange.ValidateRange when the range start falls outside the valid port interval [MinPort, MaxPort]. It is raised as ArgumentOutOfRangeException naming the start parameter, enforcing that port ranges given to the DCP port allocator are well-formed.

Solutions

Set range start to a value between 1 and 65535 inclusive.
If you intended automatic port assignment, do not supply a fixed range start.
Validate configured ranges at startup with IsValidPort before passing them on.

Example fix

// before
PortRange.ValidateRange(0, 1024, nameof(start), nameof(end));
// after
PortRange.ValidateRange(1, 1024, nameof(start), nameof(end));

Defensive patterns

Strategy: validation

Validate before calling

if (start is < 1 or > 65535)
    throw new ArgumentException($"Port range start {start} must be between 1 and 65535.");

Try / catch

try { PortRange.ValidateRange(start, end, nameof(start), nameof(end)); }
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == nameof(start)) { /* fix configured start */ }

Prevention

Validate port ranges from config at startup with IsValidPort.
Never use 0 as a literal range start; 0 means auto-assign and is not a valid range endpoint.
Parse config values with int.TryParse and range-check immediately.

When it happens

Trigger: Calling ValidateRange (or APIs that accept a port range, e.g. dev-mode port allocation settings) with a rangeStart below MinPort (1) or above MaxPort (65535), such as 0 or -1 or 70000.

Common situations: Typo in configured port range (e.g. "0-1024"); using 0 meaning 'auto-assign' where a concrete start is required; environment config values misparsed as numbers.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/4caa23c31cfb7088. Report an issue: GitHub.

Appendix: source

Thrown at src/Aspire.Hosting/Dcp/PortRange.cs:38

    public const int MaxPort = 65535;

    /// <summary>
    /// Returns <see langword="true"/> when <paramref name="port"/> is a usable port number.
    /// </summary>
    public static bool IsValidPort(int port)
    {
        return port is >= MinPort and <= MaxPort;
    }

    /// <summary>
    /// Validates that <paramref name="rangeStart"/> and <paramref name="rangeEnd"/> form a valid,
    /// non-empty, ordered port range, throwing if not.
    /// </summary>
    public static void ValidateRange(int rangeStart, int rangeEnd, string rangeStartParamName, string rangeEndParamName)
    {
        if (!IsValidPort(rangeStart))
        {
            throw new ArgumentOutOfRangeException(rangeStartParamName, rangeStart, $"Port range start must be between {MinPort} and {MaxPort}.");
        }

        if (!IsValidPort(rangeEnd))
        {
            throw new ArgumentOutOfRangeException(rangeEndParamName, rangeEnd, $"Port range end must be between {MinPort} and {MaxPort}.");
        }

        if (rangeStart > rangeEnd)
        {
            throw new ArgumentException("Port range start must be less than or equal to the range end.", rangeStartParamName);
        }
    }
}

View on GitHub (pinned to 25830f84bd)