microsoft/aspire · error · InvalidOperationException

A Container could not be configured. Ensure valid…

Error message

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

What it means

The keyed Cosmos container factory requires a container name. When connection info was parsed from the connection string, the parsed ContainerName is empty, so Aspire refuses to create an ambiguous GetContainer(...) call and throws. The container name must come from the connection string (Database=...,Container=...) or default to the registered service name.

Solutions

Append 'Container=<name>' to the 'ConnectionStrings:{name}' connection string.
Or remove any partial connection info so the keyed service name itself is used as the container name.
Ensure the connection string format is valid so parsing yields a non-empty ContainerName.

Example fix

// before
"ConnectionStrings": { "orders": "AccountEndpoint=https://acct.documents.azure.com/;AccountKey=...;Database=shop" }
// after
"ConnectionStrings": { "orders": "AccountEndpoint=https://acct.documents.azure.com/;AccountKey=...;Database=shop;Container=orders" }

Defensive patterns

Strategy: validation

Validate before calling

// before resolving the keyed container
var cs = builder.Configuration.GetConnectionString(name);
if (cs is not null && !cs.Contains("Container="))
{
    throw new InvalidOperationException($"Cosmos container name missing in connection string '{name}'.");
}

Type guard

bool HasContainerName(string? cs) => cs is null || cs.Contains("Container="); // null cs means service-name fallback is used

Try / catch

try { var container = sp.GetRequiredKeyedService<Container>(name); }
catch (InvalidOperationException ex) when (ex.Message.Contains("A Container could not be configured")) { logger.LogError(ex, "Cosmos container name missing for {Name}", name); throw; }

Prevention

Keep 'Container=' in Cosmos connection strings when any other connection info is present.
Name the keyed service after the container so the fallback is always correct.
Validate connection-string keys with a unit test against your appsettings.

When it happens

Trigger: Calling AddKeyedAzureCosmosContainer where the connection string explicitly provides connection info but contains no 'Container=' entry, then resolving the keyed Container service.

Common situations: Connection string copied from Azure portal contains only account key/endpoint; developer renames the keyed service but forgets to update 'Container=' in the connection string; partial connection-string parsing yields an empty container key.

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

Appendix: source

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

    /// <summary>
    /// Register a <see cref="Container"/> against the database managed with <see cref="CosmosDatabaseBuilder"/> as a
    /// keyed singleton.
    /// </summary>
    /// <param name="name">The name of the container to register.</param>
    /// <returns>A <see cref="CosmosDatabaseBuilder"/> that can be used for further chaining.</returns>
    public CosmosDatabaseBuilder AddKeyedContainer(string name)
    {
        _client ??= AspireMicrosoftAzureCosmosExtensions.GetCosmosClient(connectionName, settings, clientOptions);

        var connectionInfo = hostBuilder.GetCosmosConnectionInfo(name);

        hostBuilder.Services.AddKeyedSingleton(name, (sp, _) =>
        {
            // If a connection string was provided, check that it contains a valid container name.
            if (connectionInfo is not null && string.IsNullOrEmpty(connectionInfo?.ContainerName))
            {
                throw new InvalidOperationException(
                    $"A Container could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{name}'");
            }

            // Use the container name from the connection string if provided, otherwise use the name
            return _client.GetContainer(settings.DatabaseName, connectionInfo?.ContainerName ?? name);
        });

        return this;
    }
}

View on GitHub (pinned to 25830f84bd)