dotnet/orleans · critical · InvalidOperationException

Orleans:AdvertisedIPAddress must contain the Container Apps

Error message

Orleans:AdvertisedIPAddress must contain the Container Apps environment private IP.

What it means

An InvalidOperationException thrown by ConfigureOrleansEndpoints when Orleans:AdvertisedIPAddress is present (so the dev shortcut is skipped) but cannot be parsed as an IP address by IPAddress.TryParse. In Azure Container Apps the silo must advertise the environment's private IP; a malformed value would cause cluster-membership failure, so it is rejected at startup.

Source

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

public static class OrleansEndpointConfigurationExtensions
{
    public static ISiloBuilder ConfigureSampleEndpoints(
        this ISiloBuilder siloBuilder,
        IConfiguration configuration,
        IHostEnvironment environment,
        int developmentSiloPort,
        int developmentGatewayPort)
    {
        var advertisedIpValue = configuration["Orleans:AdvertisedIPAddress"];
        if (environment.IsDevelopment() && string.IsNullOrWhiteSpace(advertisedIpValue))
        {
            return siloBuilder.ConfigureEndpoints(developmentSiloPort, developmentGatewayPort);
        }

        if (!IPAddress.TryParse(advertisedIpValue, out var advertisedIp))
        {
            throw new InvalidOperationException(
                "Orleans:AdvertisedIPAddress must contain the Container Apps environment private IP.");
        }

        var advertisedSiloPort = GetRequiredPort(configuration, "Orleans:AdvertisedSiloPort");
        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)
    {

View on GitHub (pinned to fca799fa70)

Solutions

1. Set Orleans:AdvertisedIPAddress to the container app's private IP (an IPv4/IPv6 literal).
2. If you used a hostname, resolve it to an IP first (the code expects a literal, not a name).
3. For local dev, leave it unset so the IsDevelopment branch configures endpoints automatically.

Example fix

// before (config)
"Orleans": { "AdvertisedIPAddress": "my-silo.contoso.com" }

// after
"Orleans": { "AdvertisedIPAddress": "10.0.0.12" }

var ip = configuration["Orleans:AdvertisedIPAddress"];
if (!IPAddress.TryParse(ip, out _))
    throw new InvalidOperationException("Orleans:AdvertisedIPAddress must be an IP literal (the Container Apps private IP).");

When it happens

Trigger: The host is not Development (or AdvertisedIPAddress is set) and the configured value is not a parseable IP (e.g., a hostname, 'localhost', empty after dev check, or a typo). IPAddress.TryParse returns false.

Common situations: Setting a DNS hostname instead of an IP. Using 'localhost' in a container app. A placeholder like '<private-ip>' left in the config. Missing the variable so the value is null.

Related errors

• {key} must be a valid TCP port.
• Configure AzureTable:ServiceUri for Azure, or use Azurite wi
• {key} is not configured.
• graintype, siloNameFilter, and upperbound must be specified
• WEBSITE_PRIVATE_PORTS must contain at least one TCP port.

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