microsoft/aspire · error · InvalidOperationException

The configured container name of

Error message

The configured container name of '{settings.BlobContainerName}' does not exist, so an attempt was made to create it automatically and this operation failed. Please ensure the container exists and is specified in the connection string, or if you have provided a BlobContainerName in settings, please ensure it exists. If you don't supply a container name, Aspire will attempt to create one with the name 'namespace-hub-consumergroup'.

What it means

Aspire auto-creates the checkpoint blob container via containerClient.CreateIfNotExists() when processing checkpoints with EventProcessorClient. If the Azure Storage service returns a RequestFailedException (container name invalid, storage account unreachable, auth failure), Aspire wraps it in this InvalidOperationException explaining that the configured container name doesn't exist and automatic creation failed.

Solutions

Create the blob container manually in the storage account (portal/CLI/Storage Explorer) so CreateIfNotExists only needs read access.
Verify BlobContainerName is valid: lowercase, 3-63 characters, letters/digits/hyphens only.
Check the BlobServiceClient's credentials/connection target — confirm the storage account exists, is reachable, and the credential has write permission.
Inspect the inner RequestFailedException for the actual storage error code (AuthorizationFailure, AccountNotFound, etc.) and fix that root cause.
If auto-create is undesired in production, pre-provision the container via IaC (Bicep/Terraform).

Example fix

// before
settings.BlobContainerName = "Checkpoints"; // uppercase — invalid container name, create fails
// after
settings.BlobContainerName = "checkpoints"; // valid, or pre-create container and grant read access

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate container name format before wiring (lowercase, 3-63 chars, a-z0-9-hyphen)
if (settings.BlobContainerName is not null &&
    !System.Text.RegularExpressions.Regex.IsMatch(settings.BlobContainerName, "^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$"))
    throw new ArgumentException("Invalid blob container name.");

Try / catch

try { await processor.StartProcessingAsync(); } catch (InvalidOperationException ex) when (ex.InnerException is RequestFailedException rf) { logger.LogError(rf, "Blob container create failed: {Code}", rf.ErrorCode); throw; }

Prevention

Pre-provision the checkpoint container via IaC and grant only read/list to the app
Enforce lowercase container names in code review or an options validator
Verify storage account network rules/firewall allow your app in each environment
Check the inner RequestFailedException ErrorCode to distinguish permissions vs connectivity
Ensure Azurite is running when using the emulator locally

When it happens

Trigger: GetBlobContainerClient's call to containerClient.CreateIfNotExists() throwing RequestFailedException — e.g. container name violates naming rules, storage account/connection string invalid, no network access, or insufficient permissions (no 'Microsoft.Storage/storageAccounts/blobServices/containers/write').

Common situations: BlobContainerName set with uppercase characters or invalid characters (container names must be lowercase alphanumeric plus hyphen, 3-63 chars); storage emulator (Azurite) not running; firewall blocking storage account; SAS/account key lacking create permission; private endpoint DNS failures.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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

Appendix: source

Thrown at src/Components/Aspire.Azure.Messaging.EventHubs/EventProcessorClientComponent.cs:120

        {
            // If not, we'll create a container name based on the namespace, event hub name and consumer group
            var ns = GetNamespaceFromSettings(settings);

            settings.BlobContainerName = $"{ns}-{settings.EventHubName}-{consumerGroup}";
            shouldTryCreateIfNotExists = true;
        }

        var containerClient = blobClient.GetBlobContainerClient(settings.BlobContainerName);

        if (shouldTryCreateIfNotExists)
        {
            try
            {
                containerClient.CreateIfNotExists();
            }
            catch (RequestFailedException ex)
            {
                throw new InvalidOperationException(
                    $"The configured container name of '{settings.BlobContainerName}' does not exist, " +
                    "so an attempt was made to create it automatically and this operation failed. Please ensure the container " +
                    "exists and is specified in the connection string, or if you have provided a BlobContainerName in settings, please " +
                    "ensure it exists. If you don't supply a container name, Aspire will attempt to create one with the name 'namespace-hub-consumergroup'.",
                    ex);
            }
        }

        return containerClient;
    }
}

View on GitHub (pinned to 25830f84bd)