microsoft/aspire · error · InvalidOperationException

The connection string

Error message

The connection string '{connectionName}' does not exist or is missing the container name or database name.

What it means

AddAzureCosmosContainer registers a singleton Container. It requires both DatabaseName and ContainerName in the resolved Cosmos settings; if either is missing, no container can be identified and Aspire throws inside the singleton factory.

Solutions

  1. Set DatabaseName and ContainerName in the 'Aspire:Microsoft:Azure:Cosmos:{connectionName}' config section (or 'Aspire:Microsoft:Azure:Cosmos' globally).
  2. Provide them via the configureSettings callback: settings.DatabaseName = "db"; settings.ContainerName = "items";.
  3. Ensure ConnectionStrings:{connectionName} exists and, if it carries the database/container, that it is formatted as expected by the component.
  4. Verify the connectionName argument matches the configuration key.

Example fix

// before
builder.AddAzureCosmosContainer("cosmos"); // DatabaseName/ContainerName unset
// after
// appsettings.json:
// "Aspire:Microsoft:Azure:Cosmos:cosmos": { "DatabaseName": "todos", "ContainerName": "items" }
builder.AddAzureCosmosContainer("cosmos");
Defensive patterns

Strategy: validation

Validate before calling

var section = builder.Configuration.GetSection("Aspire:Microsoft:Azure:Cosmos:cosmos");
if (string.IsNullOrEmpty(section["DatabaseName"]) || string.IsNullOrEmpty(section["ContainerName"]))
    throw new InvalidOperationException("Set DatabaseName and ContainerName before calling AddAzureCosmosContainer.");

Try / catch

try { container.GetItemQueryIterator<dynamic>("SELECT * c").ReadNextAsync(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("missing the container name or database name"))
{
    logger.LogError(ex, "Cosmos container/database name missing for 'cosmos'.");
    throw;
}

Prevention

When it happens

Trigger: Calling AddAzureCosmosContainer where the connection string '{connectionName}' does not exist under ConnectionStrings, or exists but does not encode database/container names, and settings.DatabaseName/ContainerName were not provided in the 'Aspire:Microsoft:Azure:Cosmos' config section.

Common situations: Connection string is only an account endpoint (no db/container info); DatabaseName/ContainerName keys misspelled or nested at wrong level; calling AddAzureCosmosContainer before AddAzureCosmosClient-style configuration that would populate settings; using account-level connection string intended only for the client API.

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/5c0fd0b796b6423d. Report an issue: GitHub.

Appendix: source

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

    /// must contain the database name and container name or be set in the <paramref name="configureSettings" />
    /// callback. To interact with multiple containers against the same database, use
    /// <see cref="CosmosDatabaseBuilder"/> to register the database and then call
    /// <see cref="CosmosDatabaseBuilder.AddKeyedContainer(string)"/> for each container.
    /// </remarks>
    /// <exception cref="InvalidOperationException">If required ConnectionString is not provided in configuration section</exception>
    public static void AddAzureCosmosContainer(
        this IHostApplicationBuilder builder,
        string connectionName,
        Action<MicrosoftAzureCosmosSettings>? configureSettings = null,
        Action<CosmosClientOptions>? configureClientOptions = null)
    {
        var settings = builder.GetSettings(connectionName, configureSettings);
        var clientOptions = builder.GetClientOptions(settings, configureClientOptions);
        builder.Services.AddSingleton(sp =>
        {
            if (string.IsNullOrEmpty(settings.ContainerName) || string.IsNullOrEmpty(settings.DatabaseName))
            {
                throw new InvalidOperationException($"The connection string '{connectionName}' does not exist or is missing the container name or database name.");
            }
            var client = GetCosmosClient(connectionName, settings, clientOptions);
            return client.GetContainer(settings.DatabaseName, settings.ContainerName);
        });
    }

    /// <summary>
    /// Registers the <see cref="CosmosClient" /> as a singleton for given <paramref name="name" /> in the services provided by the <paramref name="builder"/>.
    /// Configures logging and telemetry for the <see cref="CosmosClient" />.
    /// </summary>
    /// <param name="builder">The <see cref="IHostApplicationBuilder" /> to read config from and add services to.</param>
    /// <param name="name">The name of the component, which is used as the <see cref="ServiceDescriptor.ServiceKey"/> of the service and also to retrieve the connection string from the ConnectionStrings configuration section.</param>
    /// <param name="configureSettings">An optional method that can be used for customizing the <see cref="MicrosoftAzureCosmosSettings"/>. It's invoked after the settings are read from the configuration.</param>
    /// <param name="configureClientOptions">An optional method that can be used for customizing the <see cref="CosmosClientOptions"/>.</param>
    /// <remarks>Reads the configuration from "Aspire:Microsoft:Azure:Cosmos:{name}" section.</remarks>
    /// <exception cref="InvalidOperationException">If required ConnectionString is not provided in configuration section</exception>
    public static void AddKeyedAzureCosmosClient(
        this IHostApplicationBuilder builder,

View on GitHub (pinned to 25830f84bd)