dotnet/orleans · critical · InvalidOperationException

The required setting '{name}' isn't configured.

Error message

The required setting '{name}' isn't configured.

What it means

An InvalidOperationException thrown by the GetRequiredSetting helper in the Azure App Service silo Program.cs when a required configuration key (e.g., ORLEANS_CLUSTER_ID, ORLEANS_SERVICE_ID, ORLEANS_AZURE_STORAGE_URI, AZURE_CLIENT_ID, WEBSITE_PRIVATE_IP) is null or whitespace. It is a fail-fast guard ensuring the silo cannot start half-configured.

Source

Thrown at samples/Deployment/AzureAppService/Silo/Program.cs:155

            .UseAzureStorageClustering(options =>
            {
                options.TableServiceClient = tableServiceClient;
                options.TableName = $"{clusterId}Clustering";
            })
            .AddAzureTableGrainStorage(
                "shopping-cart",
                options =>
                {
                    options.TableServiceClient = tableServiceClient;
                    options.TableName = $"{clusterId}Persistence";
                });
    });
}

static string GetRequiredSetting(WebApplicationBuilder builder, string name) =>
    builder.Configuration[name] is { } value && !string.IsNullOrWhiteSpace(value)
        ? value
        : throw new InvalidOperationException($"The required setting '{name}' isn't configured.");

View on GitHub (pinned to fca799fa70)

Solutions

1. Set every required key listed in the error's 'name' placeholder in the App Service Configuration blade (or local environment/appsettings).
2. Cross-check the keys against the deployment template (Bicep/ARM/terraform) that provisions the App Service.
3. Add a startup config-validation log that dumps which keys resolved, to catch misnamed keys early.

Example fix

// before
static string GetRequiredSetting(WebApplicationBuilder builder, string name) =>
    builder.Configuration[name] is { } value && !string.IsNullOrWhiteSpace(value)
        ? value
        : throw new InvalidOperationException($"The required setting '{name}' isn't configured.");

// after (list all missing keys at once)
static string GetRequiredSetting(WebApplicationBuilder builder, string name)
{
    var value = builder.Configuration[name];
    if (string.IsNullOrWhiteSpace(value))
        throw new InvalidOperationException(
            $"The required setting '{name}' isn't configured. " +
            $"Configured keys starting with 'ORLEANS': " +
            $"{string.Join(", ", builder.Configuration.AsEnumerable().Where(kv => kv.Key.StartsWith("ORLEANS")).Select(kv => kv.Key))}.");
    return value;
}

string[] required = ["ORLEANS_CLUSTER_ID","ORLEANS_SERVICE_ID","ORLEANS_AZURE_STORAGE_URI","AZURE_CLIENT_ID","WEBSITE_PRIVATE_IP","WEBSITE_PRIVATE_PORTS"];
var missing = required.Where(k => string.IsNullOrWhiteSpace(builder.Configuration[k])).ToList();
if (missing.Count > 0) throw new InvalidOperationException("Missing settings: " + string.Join(", ", missing));

When it happens

Trigger: Any of the required settings passed to GetRequiredSetting is absent from builder.Configuration (appsettings, env vars, App Service settings). The null-coalesce + IsNullOrWhiteSpace check triggers the throw naming the missing key.

Common situations: Deploying the App Service without configuring the application settings. Renaming a key in code but not in the deployment template (Bicep/ARM). Local run missing environment variables.

Related errors

• WEBSITE_PRIVATE_PORTS must contain at least one TCP port.
• AzureTable:ServiceUri must be an absolute HTTPS Azure Table
• AZURE_CLIENT_ID must contain the user-assigned managed ident
• Configure AzureTable:ServiceUri for Azure, or use Azurite wi
• {key} is not configured.

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