microsoft/aspire · error · InvalidOperationException

A Database could not be configured. Ensure valid connection…

Error message

A Database could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}'.

What it means

CosmosDatabaseBuilder.AddDatabase lazily creates the Database singleton. It requires settings.DatabaseName to be set; without a database name, GetDatabase cannot be called. The message also hints that the database name usually comes from the connection string for Cosmos in Aspire.

Solutions

Set DatabaseName in 'Aspire:Microsoft:Azure:Cosmos:{connectionName}' config (or global 'Aspire:Microsoft:Azure:Cosmos' section).
Set it in code: builder.AddAzureCosmosDatabase("cosmos", settings => settings.DatabaseName = "mydb");.
Ensure ConnectionStrings:{connectionName} exists and includes the database name when using the connection-string convention.
Also make sure the account connection itself resolves, since AddDatabase lazily builds the CosmosClient too.

Example fix

// before
builder.AddAzureCosmosDatabase("cosmos"); // DatabaseName unset
// after
// appsettings.json: "Aspire:Microsoft:Azure:Cosmos:cosmos": { "DatabaseName": "orders" }
builder.AddAzureCosmosDatabase("cosmos");

Defensive patterns

Strategy: validation

Validate before calling

var dbName = builder.Configuration["Aspire:Microsoft:Azure:Cosmos:cosmos:DatabaseName"];
if (string.IsNullOrEmpty(dbName))
    throw new InvalidOperationException("DatabaseName must be configured (or present in the connection string) before AddAzureCosmosDatabase.");

Try / catch

try { database.GetContainerQueryIterator().ReadNextAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("A Database could not be configured"))
{
    logger.LogError(ex, "Cosmos database name missing for 'cosmos'.");
    throw;
}

Prevention

Always supply DatabaseName via config or configureSettings when calling AddAzureCosmosDatabase.
Verify the connection string format includes the database when relying on it for the name.
Add a startup validation that resolves the Database before the app accepts traffic.

When it happens

Trigger: Calling AddAzureCosmosDatabase(connectionName) where the connection string '{connectionName}' does not exist or does not include the database name, and settings.DatabaseName was not set in the 'Aspire:Microsoft:Azure:Cosmos' config section or via configureSettings.

Common situations: Connection string points only to the account endpoint without a database path; developer expected AddDatabase to default to a database in config; database name keys in config misspelled; keyed/non-keyed name mismatch.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/6437154fce46f14e. Report an issue: GitHub.

Appendix: source

Thrown at src/Components/Aspire.Microsoft.Azure.Cosmos/CosmosDatabaseBuilder.cs:28

/// <summary>
/// Represents a builder that can be used to register multiple container
/// instances against the same Cosmos database connection.
/// </summary>
public sealed class CosmosDatabaseBuilder(
    IHostApplicationBuilder hostBuilder,
    string connectionName,
    MicrosoftAzureCosmosSettings settings,
    CosmosClientOptions clientOptions)
{
    private CosmosClient? _client;

    internal CosmosDatabaseBuilder AddDatabase()
    {
        hostBuilder.Services.AddSingleton(sp =>
        {
            if (string.IsNullOrEmpty(settings.DatabaseName))
            {
                throw new InvalidOperationException(
                    $"A Database could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}'.");
            }
            _client ??= AspireMicrosoftAzureCosmosExtensions.GetCosmosClient(connectionName, settings, clientOptions);
            return _client.GetDatabase(settings.DatabaseName);
        });

        return this;
    }

    internal CosmosDatabaseBuilder AddKeyedDatabase()
    {
        hostBuilder.Services.AddKeyedSingleton(connectionName, (sp, _) =>
        {
            if (string.IsNullOrEmpty(settings.DatabaseName))
            {
                throw new InvalidOperationException(
                    $"A Database could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}'.");
            }

View on GitHub (pinned to 25830f84bd)