dotnet/orleans · critical · OrleansConfigurationException

Configuration for Azure Cosmos DB provider {_name} is invali

Error message

Configuration for Azure Cosmos DB provider {_name} is invalid. You must call ConfigureCosmosClient to configure access to Azure Cosmos DB.

What it means

Thrown by CosmosOptionsValidator.ValidateConfiguration at startup when CosmosOptions.CreateClient is null, meaning ConfigureCosmosClient was never called. The provider cannot reach Cosmos without a client factory.

Source

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

    {
        _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. Call options.ConfigureCosmosClient(endpoint, authKeyOrResourceToken) or the delegate overload.
2. Verify the configure call is on the options instance/name that the validator checks.
3. If using TokenCredential, use the delegate overload to build the CosmosClient with the credential.

Example fix

// before
// no ConfigureCosmosClient call

// after
options.ConfigureCosmosClient(endpoint, authKey);
// or
options.ConfigureCosmosClient(sp => new(new CosmosClient(endpoint, tokenCredential, options.ClientOptions)));

if (options.CreateClient is null)
    throw new OrleansConfigurationException("Call ConfigureCosmosClient before startup");

static bool IsConfigured(CosmosOptions o) => o.CreateClient is not null;

When it happens

Trigger: Registering a Cosmos provider but omitting the .ConfigureCosmosClient(...) call.

Common situations: Following a partial sample; refactor that removed the client configuration; switching from connection-string to credential-based client without adding the configure call.

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/9d522d651e9af421. Report an issue: GitHub.