dotnet/orleans · critical · OrleansConfigurationException

Configuration for Azure Cosmos DB provider {_name} is invali

Error message

Configuration for Azure Cosmos DB provider {_name} is invalid. CosmosOptions.ContainerName is not valid.

What it means

Thrown by CosmosOptionsValidator.ValidateConfiguration at startup when CosmosOptions.ContainerName is null, empty, or whitespace. The Cosmos provider must target a specific container.

Source

Thrown at src/Azure/Shared/Cosmos/CosmosOptionsValidator.cs:43

    /// Initializes a new instance of the <see cref="CosmosOptionsValidator{TOptions}"/> type.
    /// </summary>
    /// <param name="options">The instance to be validated.</param>
    /// <param name="name">The option name to be validated.</param>
    public CosmosOptionsValidator(TOptions options, string name)
    {
        _options = options;
        _name = name;
    }

    /// <inheritdoc/>
    public void ValidateConfiguration()
    {
        if (string.IsNullOrWhiteSpace(_options.DatabaseName))
            throw new OrleansConfigurationException(
                $"Configuration for Azure Cosmos DB provider {_name} is invalid. {nameof(_options.DatabaseName)} is not valid.");

        if (string.IsNullOrWhiteSpace(_options.ContainerName))
            throw new OrleansConfigurationException(
                $"Configuration for Azure Cosmos DB provider {_name} is invalid. {nameof(_options.ContainerName)} is not valid.");

        if (_options.CreateClient is null)
        {
            throw new OrleansConfigurationException(
                $"Configuration for Azure Cosmos DB provider {_name} is invalid. You must call {nameof(_options.ConfigureCosmosClient)} to configure access to Azure Cosmos DB.");
        }
    }
}

View on GitHub (pinned to fca799fa70)

Solutions

1. Set options.ContainerName to a non-empty container name.
2. Verify the configuration section binding includes the ContainerName key.
3. Confirm the container exists in the Cosmos database.

Example fix

// before
// config: { "DatabaseName": "Orleans" } // no ContainerName

// after
// config: { "DatabaseName": "Orleans", "ContainerName": "grainState" }

if (string.IsNullOrWhiteSpace(options.ContainerName))
    throw new OrleansConfigurationException("ContainerName required");

static bool HasContainerName(CosmosOptions o) => !string.IsNullOrWhiteSpace(o.ContainerName);

When it happens

Trigger: Configuring a Cosmos-backed provider without setting ContainerName.

Common situations: Missing ContainerName key in appsettings; wrong config binding; sample omission.

Related errors

• Configuration for Azure Cosmos DB provider {_name} is invali
• Configuration for Azure Cosmos DB provider {_name} is invali
• Azure Event Hub connection not configured for stream provide
• EventHubOptions on stream provider {this.name} is invalid. E
• EventHubOptions on stream provider {this.name} is invalid. E

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