microsoft/aspire · error · InvalidOperationException

A QueueClient could not be configured. Ensure valid…

Error message

A QueueClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify a 'ConnectionString' or 'ServiceUri' in the '{configurationSectionName}' configuration section.

What it means

Like the QueueServiceClient variant, this is thrown when a QueueClient cannot be constructed because neither a connection string nor a ServiceUri was provided. It fires only after the queue-name check passes, so the queue name was configured but no endpoint/connection information resolved.

Solutions

Add 'ConnectionStrings:{connectionName}' with the storage account connection string or service URI in appsettings.json or user secrets.
Run the app under the Aspire AppHost so the connection string is injected automatically.
Set 'ServiceUri' (e.g. https://account.queue.core.windows.net) under the 'Aspire:Azure:Storage:Queues' config section.
Verify config is actually loaded (correct appsettings.{Environment}.json, secrets initialized).

Example fix

// before
builder.AddAzureQueueClient("queues"); // QueueName set, but no connection
// after
// appsettings.json: "ConnectionStrings": { "queues": "DefaultEndpointsProtocol=https;AccountName=acct;AccountKey=..." }
builder.AddAzureQueueClient("queues");

Defensive patterns

Strategy: validation

Validate before calling

var hasConnection = !string.IsNullOrEmpty(builder.Configuration.GetConnectionString("queues"));
var serviceUri = builder.Configuration["Aspire:Azure:Storage:Queues:ServiceUri"];
if (!hasConnection && string.IsNullOrEmpty(serviceUri))
    throw new InvalidOperationException("Provide ConnectionStrings:queues or Aspire:Azure:Storage:Queues:ServiceUri.");

Try / catch

try { /* resolve QueueClient */ }
catch (InvalidOperationException ex) when (ex.Message.Contains("A QueueClient could not be configured"))
{
    logger.LogError(ex, "Missing queue connection info for 'queues'.");
    throw;
}

Prevention

Verify both QueueName and connection info are configured when using AddAzureQueueClient.
Run through the AppHost during local development to catch missing injected connections early.
Add a health check against the queue client at startup.

When it happens

Trigger: Calling AddAzureQueueClient with a valid QueueName (or queue-bearing connection) but 'ConnectionStrings:{connectionName}' missing and no 'ConnectionString'/'ServiceUri' in the '{configurationSectionName}' config section.

Common situations: Queue name set in the Aspire:Azure:Storage:Queues section but connection string forgotten; running without the AppHost-provided connection; key typo in ConnectionStrings; config not loaded (wrong environment).

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

Appendix: source

Thrown at src/Components/Aspire.Azure.Storage.Queues/AspireQueueStorageExtensions.cs:246

            => !settings.DisableTracing;
    }

    private sealed partial class StorageQueueComponent : AzureComponent<AzureStorageQueueSettings, QueueClient, QueueClientOptions>
    {
        protected override IAzureClientBuilder<QueueClient, QueueClientOptions> AddClient(
            AzureClientFactoryBuilder azureFactoryBuilder, AzureStorageQueueSettings settings, string connectionName, string configurationSectionName)
        {
            return ((IAzureClientFactoryBuilderWithCredential)azureFactoryBuilder).RegisterClientFactory<QueueClient, QueueClientOptions>((options, cred) =>
            {
                if (string.IsNullOrEmpty(settings.QueueName))
                {
                    throw new InvalidOperationException($"The connection string '{connectionName}' does not exist or is missing the queue name.");
                }

                var connectionString = settings.ConnectionString;
                if (string.IsNullOrEmpty(connectionString) && settings.ServiceUri is null)
                {
                    throw new InvalidOperationException($"A QueueClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify a 'ConnectionString' or 'ServiceUri' in the '{configurationSectionName}' configuration section.");
                }

                var queueServiceClient = !string.IsNullOrEmpty(connectionString) ? new QueueServiceClient(connectionString, options) :
                    cred is not null ? new QueueServiceClient(settings.ServiceUri, cred, options) :
                    new QueueServiceClient(settings.ServiceUri, options);

                var client = queueServiceClient.GetQueueClient(settings.QueueName);
                return client;
            }, requiresCredential: false);
        }

        protected override void BindClientOptionsToConfiguration(IAzureClientBuilder<QueueClient, QueueClientOptions> clientBuilder, IConfiguration configuration)
        {
#pragma warning disable IDE0200 // Remove unnecessary lambda expression - needed so the ConfigBinder Source Generator works
            clientBuilder.ConfigureOptions(options => configuration.Bind(options));
#pragma warning restore IDE0200
        }

View on GitHub (pinned to 25830f84bd)