What causes "{key} must be a valid TCP port." in dotnet/orleans?

Set both Orleans:AdvertisedSiloPort and Orleans:AdvertisedGatewayPort to integers in 1..65535.

dotnet/orleans · critical · InvalidOperationException

{key} must be a valid TCP port.

Error message

{key} must be a valid TCP port.

What it means

An InvalidOperationException thrown by GetRequiredPort when an Orleans advertised port setting (Orleans:AdvertisedSiloPort or Orleans:AdvertisedGatewayPort) is missing or not a valid unsigned TCP port in the range 1..65535. The value is parsed with NumberStyles.None (no sign) and range-checked against IPEndPoint.MaxPort.

Source

Thrown at samples/Deployment/AzureContainerApps/Infrastructure/OrleansEndpointConfigurationExtensions.cs:49

        var advertisedGatewayPort = GetRequiredPort(configuration, "Orleans:AdvertisedGatewayPort");

        return siloBuilder.Configure<EndpointOptions>(options =>
        {
            options.AdvertisedIPAddress = advertisedIp;
            options.SiloPort = advertisedSiloPort;
            options.GatewayPort = advertisedGatewayPort;
            options.SiloListeningEndpoint = new IPEndPoint(IPAddress.Any, 11_111);
            options.GatewayListeningEndpoint = new IPEndPoint(IPAddress.Any, 30_000);
        });
    }

    private static int GetRequiredPort(IConfiguration configuration, string key)
    {
        var value = AzureTableServiceClientFactory.GetRequiredValue(configuration, key);
        if (!int.TryParse(value, NumberStyles.None, CultureInfo.InvariantCulture, out var port)
            || port is < 1 or > IPEndPoint.MaxPort)
        {
            throw new InvalidOperationException($"{key} must be a valid TCP port.");
        }

        return port;
    }
}

View on GitHub (pinned to fca799fa70)

Solutions

Set both Orleans:AdvertisedSiloPort and Orleans:AdvertisedGatewayPort to integers in 1..65535.
Ensure the values are plain unsigned integers (no '+', '-', whitespace, hex).
Confirm the container app exposes/permits those ports in its ingress/ports config.

Example fix

// before (config)
"Orleans": { "AdvertisedSiloPort": "0", "AdvertisedGatewayPort": "30000" }

// after
"Orleans": { "AdvertisedSiloPort": "11111", "AdvertisedGatewayPort": "30000" }

Defensive patterns

Strategy: validation

Validate before calling

static int CheckPort(IConfiguration c, string key) {
    var v = c[key];
    if (!int.TryParse(v, NumberStyles.None, CultureInfo.InvariantCulture, out var p) || p is < 1 or > IPEndPoint.MaxPort)
        throw new InvalidOperationException($"{key} must be a TCP port in 1..65535.");
    return p;
}

Prevention

Set advertised ports to plain unsigned integers within 1..65535.
Ensure the container app exposes those ports.
Validate ports in a startup config check before binding endpoints.

When it happens

Trigger: A port key is unset, non-numeric, negative, zero, or > 65535. The int.TryParse fails or the 'is < 1 or > MaxPort' pattern matches.

Common situations: Port env vars not provisioned in the container app. A value like '0', '-1', '65536', or a string. Misnamed keys so GetRequiredValue returns the not-configured error first.

Related errors

AI-assisted analysis of dotnet/orleans@fca799fa70 (2026-08-13). Data as JSON: /api/errors/1d56450fcdb8148b. Report an issue: GitHub.