dotnet/orleans · error · OrleansConfigurationException

Configuration for AzureBlobStorageOptions {name} is invalid.

Error message

Configuration for AzureBlobStorageOptions {name} is invalid. ContainerName is not valid

What it means

Thrown by AzureBlobStorageOptionsValidator.ValidateConfiguration() when AzureBlobUtils.ValidateContainerName or ValidateBlobName raises an ArgumentException, wrapped into an OrleansConfigurationException. The container name must be 3-63 chars, lowercase alphanumeric with single hyphens (regex ^[a-z0-9]+(-[a-z0-9]+)*$). The blob name (which is the provider option name) must be non-empty, max 1024 chars, max 253 slashes.

Source

Thrown at src/Azure/Orleans.Persistence.AzureStorage/Providers/Storage/AzureBlobStorageOptions.cs:158

            this.options = options;
            this.name = name;
        }

        public void ValidateConfiguration()
        {
            if (this.options.CreateClient is null)
            {
                throw new OrleansConfigurationException($"No credentials specified. Use the {options.GetType().Name}.{nameof(AzureBlobStorageOptions.ConfigureBlobServiceClient)} method to configure the Azure Blob Service client.");
            }

            try
            {
                AzureBlobUtils.ValidateContainerName(options.ContainerName);
                AzureBlobUtils.ValidateBlobName(this.name);
            }
            catch (ArgumentException e)
            {
                throw new OrleansConfigurationException(
                    $"Configuration for AzureBlobStorageOptions {name} is invalid. {nameof(this.options.ContainerName)} is not valid", e);
            }
        }
    }
}

View on GitHub (pinned to fca799fa70)

Solutions

Set ContainerName to a lowercase alphanumeric string of 3-63 characters with optional single hyphens (e.g., "grain-state").
Ensure the storage provider name passed to AddAzureBlobGrainStorage is non-empty and under 1024 characters.
Check appsettings.json for the ContainerName value and fix any uppercase or special characters.
Test the name against the regex ^[a-z0-9]+(-[a-z0-9]+)*$ before deploying.

Example fix

// before
o.ContainerName = "MyGrainState_Data"; // uppercase + underscore invalid

// after
o.ContainerName = "grain-state";

Defensive patterns

Strategy: validation

Validate before calling

// Validate container name before silo start
var containerName = configuration["Orleans:Persistence:grainStore:ContainerName"];
if (!System.Text.RegularExpressions.Regex.IsMatch(containerName ?? "", @"^[a-z0-9]+(-[a-z0-9]+)*$")
    || containerName?.Length < 3 || containerName?.Length > 63)
    throw new InvalidOperationException($"Invalid container name: '{containerName}'");

Try / catch

try { await host.StartAsync(ct); }
catch (OrleansConfigurationException ex) when (ex.Message.Contains("ContainerName is not valid"))
{
    logger.LogError("Azure Blob container name is invalid — must be 3-63 lowercase alphanumeric with hyphens.");
    throw;
}

Prevention

Always set ContainerName explicitly to a known-valid value.
Use a naming convention helper that enforces the regex at compile/config time.
Add a startup health check that validates container name format.
Never use uppercase or underscores in Azure container names.

When it happens

Trigger: Fires during ValidateConfiguration() when options.ContainerName fails the container regex (e.g., uppercase letters, underscores, too short) or when the option name string fails blob name validation. ValidateContainerName runs first; if it throws, the catch wraps it.

Common situations: Container name set to a value with uppercase characters (e.g., "MyGrainState"), too short (less than 3 chars), or containing invalid characters like underscores. Using a default name that is empty or whitespace. Migration from an emulator where naming rules were not enforced.

Related errors

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