microsoft/aspire · error · InvalidOperationException

A CosmosClient could not be configured. Ensure valid…

Error message

A CosmosClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or either {nameof(settings.ConnectionString)} or {nameof(settings.AccountEndpoint)} must be provided in the '{DefaultConfigSectionName}' or '{DefaultConfigSectionName}:{connectionName}' configuration section.

What it means

GetCosmosClient builds a CosmosClient from either a connection string or an account endpoint plus credential. When neither settings.ConnectionString nor settings.AccountEndpoint resolved (from ConnectionStrings or the Aspire:Microsoft:Azure:Cosmos config sections), Aspire throws because no client can authenticate or address the account.

Solutions

Add ConnectionStrings:{connectionName} with the Cosmos account connection string or account endpoint URI.
Ensure the project references the Cosmos DB hosting resource and uses WithReference in the AppHost so the connection is injected.
Set 'ConnectionString' or 'AccountEndpoint' in the 'Aspire:Microsoft:Azure:Cosmos' (or per-connection) config section.
Verify config section names: DefaultConfigSectionName is 'Aspire:Microsoft:Azure:Cosmos'.

Example fix

// before
builder.AddAzureCosmosClient("cosmos"); // nothing configured
// after
// appsettings.json: "ConnectionStrings": { "cosmos": "AccountEndpoint=https://myacct.documents.azure.com/;AccountKey=..." }
builder.AddAzureCosmosClient("cosmos");

Defensive patterns

Strategy: validation

Validate before calling

var cs = builder.Configuration.GetConnectionString("cosmos");
var section = builder.Configuration.GetSection("Aspire:Microsoft:Azure:Cosmos");
if (string.IsNullOrEmpty(cs) && section["ConnectionString"] is null && section["AccountEndpoint"] is null)
    throw new InvalidOperationException("Configure ConnectionStrings:cosmos or Aspire:Microsoft:Azure:Cosmos (ConnectionString/AccountEndpoint) before resolving CosmosClient.");

Try / catch

try { client.ReadAccountAsync().GetAwaiter().GetResult(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("A CosmosClient could not be configured"))
{
    logger.LogError(ex, "Cosmos connection info missing for 'cosmos'.");
    throw;
}

Prevention

Register the Cosmos DB resource in the AppHost and WithReference the project.
Keep the connection name argument consistent across AppHost and client registration.
Remember client-level settings apply to Database/Container registrations too, since they lazily build the same client.

When it happens

Trigger: Calling AddAzureCosmosClient/AddKeyedAzureCosmosClient (or any API that lazily builds the client, like AddAzureCosmosDatabase/Container) where ConnectionStrings:{connectionName} is missing and no AccountEndpoint/ConnectionString is set in the 'Aspire:Microsoft:Azure:Cosmos' or 'Aspire:Microsoft:Azure:Cosmos:{connectionName}' sections.

Common situations: Running without the AppHost-injected connection string; connection name typo; AccountEndpoint configured without credentials being resolvable (different failure) versus endpoint entirely absent (this error); section name changed across package versions.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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

Appendix: source

Thrown at src/Components/Aspire.Microsoft.Azure.Cosmos/AspireMicrosoftAzureCosmosExtensions.cs:302

        clientOptions.ApplicationName = cosmosApplicationName;

        return clientOptions;
    }

    internal static CosmosClient GetCosmosClient(string connectionName, MicrosoftAzureCosmosSettings settings, CosmosClientOptions clientOptions)
    {
        if (!string.IsNullOrEmpty(settings.ConnectionString))
        {
            return new CosmosClient(settings.ConnectionString, clientOptions);
        }
        else if (settings.AccountEndpoint is not null)
        {
            var credential = settings.Credential ?? AzureCredentialHelper.CreateDefaultAzureCredential();
            return new CosmosClient(settings.AccountEndpoint.OriginalString, credential, clientOptions);
        }
        else
        {
            throw new InvalidOperationException(
                    $"A CosmosClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or either " +
                    $"{nameof(settings.ConnectionString)} or {nameof(settings.AccountEndpoint)} must be provided " +
                    $"in the '{DefaultConfigSectionName}' or '{DefaultConfigSectionName}:{connectionName}' configuration section.");
        }
    }
}

View on GitHub (pinned to 25830f84bd)