microsoft/aspire · error · InvalidOperationException

Invalid value " " for " ". Expected a port range formatted…

Error message

Invalid value "{configuredRange}" for "{KnownConfigNames.ProxylessEndpointPortRange}". Expected a port range formatted as "start-end", for example "10000-32767".

What it means

The ProxylessEndpointPortRange configuration must be formatted as "start-end" (two integers separated by a hyphen). When the configured string does not match this format, ApplyProxylessEndpointPortRangeOverride calls this dedicated throw helper producing an InvalidOperationException. It fails fast so an unparseable port range never reaches DCP endpoint allocation.

Solutions

Set the value to "start-end" format with two integers, e.g. "10000-32767"
Ensure start <= end and ports are within valid range (1-65535)
Remove the setting to use the default port range

Example fix

// before (appsettings/env)
"Aspire:Dcp:ProxylessEndpointPortRange": "10000..32767"
// after
"Aspire:Dcp:ProxylessEndpointPortRange": "10000-32767"

Defensive patterns

Strategy: validation

Validate before calling

var range = configuration[KnownConfigNames.ProxylessEndpointPortRange];
if (range is not null)
{
    var parts = range.Split('-');
    if (parts.Length != 2 || !int.TryParse(parts[0], out var s) || !int.TryParse(parts[1], out var e) || s > e || s < 1 || e > 65535)
        throw new FormatException($"Invalid port range '{range}'. Expected 'start-end', e.g. 10000-32767.");
}

Try / catch

try
{
    dcpOptions.Configure(configuration);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("start-end"))
{
    // Remove/fix the ProxylessEndpointPortRange setting and retry with defaults.
}

Prevention

Use strict "start-end" syntax with a hyphen when setting the port range
Validate start <= end and the 1-65535 bounds before setting
Do not copy range syntax from other tooling (Docker, Hyper-V)

When it happens

Trigger: Setting the KnownConfigNames.ProxylessEndpointPortRange config key (e.g. ASPNETCORE or aspire proxyless endpoint env var) to something like "10000", "10000..32767", "32767-10000" (reversed if validation rejects), or arbitrary text.

Common situations: Typos when constraining the ephemeral port range for proxyless endpoints; copying a range syntax from another tool (e.g., Docker's or Hyper-V's syntax); forgetting the hyphen separator.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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

Appendix: source

Thrown at src/Aspire.Hosting/Dcp/DcpOptions.cs:386

        var endText = configuredRange[(separatorIndex + 1)..].Trim();
        if (!int.TryParse(startText, NumberStyles.None, CultureInfo.InvariantCulture, out var start))
        {
            ThrowInvalidProxylessEndpointPortRange(configuredRange);
        }

        if (!int.TryParse(endText, NumberStyles.None, CultureInfo.InvariantCulture, out var end))
        {
            ThrowInvalidProxylessEndpointPortRange(configuredRange);
        }

        options.ProxylessEndpointPortRangeStart = start;
        options.ProxylessEndpointPortRangeEnd = end;
    }

    [DoesNotReturn]
    private static void ThrowInvalidProxylessEndpointPortRange(string configuredRange)
    {
        throw new InvalidOperationException(
            $"Invalid value \"{configuredRange}\" for \"{KnownConfigNames.ProxylessEndpointPortRange}\". Expected a port range formatted as \"start-end\", for example \"10000-32767\".");
    }

    private static string? GetMetadataValue(IEnumerable<AssemblyMetadataAttribute>? assemblyMetadata, string key)
    {
        return assemblyMetadata?.FirstOrDefault(m => string.Equals(m.Key, key, StringComparison.OrdinalIgnoreCase))?.Value;
    }
}

View on GitHub (pinned to 25830f84bd)