microsoft/aspire · error · InvalidOperationException

The connection string

Error message

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

What it means

The keyed variant of AddAzureCosmosContainer behaves identically but registers the Container under the keyed service name '{name}'. It throws the same way when the resolved settings lack DatabaseName or ContainerName.

Solutions

Configure 'Aspire:Microsoft:Azure:Cosmos:{name}': { "DatabaseName": "...", "ContainerName": "..." } with {name} exactly matching the registration name.
Set settings.DatabaseName and settings.ContainerName via the configureSettings callback.
Ensure ConnectionStrings contains an entry for '{name}' with valid Cosmos connection information.
Confirm you resolve the container with the same keyed name (e.g. AddKeyedAzureCosmosClient/container consistency).

Example fix

// before
builder.AddKeyedAzureCosmosContainer("cart"); // no config for 'cart'
// after
// appsettings.json:
// "Aspire:Microsoft:Azure:Cosmos:cart": { "DatabaseName": "shop", "ContainerName": "cart" }
builder.AddKeyedAzureCosmosContainer("cart");

Defensive patterns

Strategy: validation

Validate before calling

var section = builder.Configuration.GetSection($"Aspire:Microsoft:Azure:Cosmos:{name}");
if (string.IsNullOrEmpty(section["DatabaseName"]) || string.IsNullOrEmpty(section["ContainerName"]))
    throw new InvalidOperationException($"Keyed Cosmos container '{name}' needs DatabaseName and ContainerName configured.");

Try / catch

try { sp.GetRequiredKeyedService<Container>("cart"); }
catch (InvalidOperationException ex) when (ex.Message.Contains("missing the container name or database name"))
{
    logger.LogError(ex, "Keyed Cosmos container 'cart' missing db/container config.");
    throw;
}

Prevention

Ensure the keyed registration name exactly matches the config section key and resolution key.
Centralize keyed Cosmos names in constants to avoid mismatches.
Test keyed resolution at host startup.

When it happens

Trigger: Calling AddKeyedAzureCosmosContainer(name) where ConnectionStrings has no '{name}' entry or it lacks database/container information, and 'Aspire:Microsoft:Azure:Cosmos:{name}' does not supply DatabaseName/ContainerName.

Common situations: Keyed name not matching any configuration; configuring a different key than the one passed as name; forgetting that keyed registrations resolve via IKeyedServiceProvider with the same name used at registration.

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/8eca9ef4eda3a9ad. Report an issue: GitHub.

Appendix: source

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

    /// 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 AddKeyedAzureCosmosContainer(
        this IHostApplicationBuilder builder,
        string name,
        Action<MicrosoftAzureCosmosSettings>? configureSettings = null,
        Action<CosmosClientOptions>? configureClientOptions = null)
    {
        var settings = builder.GetSettings(name, configureSettings);
        var clientOptions = builder.GetClientOptions(settings, configureClientOptions);
        builder.Services.AddKeyedSingleton(name, (sp, key) =>
        {
            if (string.IsNullOrEmpty(settings.ContainerName) || string.IsNullOrEmpty(settings.DatabaseName))
            {
                throw new InvalidOperationException($"The connection string '{name}' does not exist or is missing the container name or database name.");
            }
            var client = GetCosmosClient(name, settings, clientOptions);
            return client.GetContainer(settings.DatabaseName, settings.ContainerName);
        });
    }

    /// <summary>
    /// Registers the <see cref="Database"/> as a singleton the services provided by the <paramref name="builder"/>
    /// and returns a <see cref="CosmosDatabaseBuilder"/> to support chaining multiple container registrations against the same database.
    /// </summary>
    /// <param name="builder">The <see cref="IHostApplicationBuilder" /> to read config from and add services to.</param>
    /// <param name="connectionName">The connection name to use to find a connection string.</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 CosmosDatabaseBuilder AddAzureCosmosDatabase(
        this IHostApplicationBuilder builder,

View on GitHub (pinned to 25830f84bd)