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.DatabaseName is not valid.

What it means

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

Source

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

    private readonly TOptions _options;
    private readonly string _name;

    /// <summary>
    /// 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.DatabaseName to a non-empty database name.
2. Verify the configuration section binding includes the DatabaseName key.
3. Confirm the database exists in the Cosmos account.

Example fix

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

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

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

static bool HasDatabaseName(CosmosOptions o) => !string.IsNullOrWhiteSpace(o.DatabaseName);

When it happens

Trigger: Configuring a Cosmos-backed grain storage or streaming provider without setting DatabaseName.

Common situations: Missing DatabaseName key in appsettings; wrong config binding; copy-paste from a sample that omits it.

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/179a58f612b6ab66. Report an issue: GitHub.