microsoft/aspire · error · InvalidOperationException

The connection string

Error message

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

What it means

The QueueClient overload requires a queue name in addition to connection information. Aspire throws this when settings.QueueName is empty, meaning the connection string (if it exists) did not supply a queue name and no queue name was configured.

Solutions

Ensure the connection string includes the queue name, e.g. a full queue URL 'https://account.queue.core.windows.net/myqueue' or set 'QueueName' in the 'Aspire:Azure:Storage:Queues:{connectionName}' config section.
Set the queue name explicitly via the configureSettings callback: settings.QueueName = "myqueue".
Confirm the connection named '{connectionName}' actually exists under ConnectionStrings.
If you don't have a specific queue, use AddAzureQueues (QueueServiceClient) instead of AddAzureQueueClient.

Example fix

// before
builder.AddAzureQueueClient("queues"); // ConnectionStrings:queues = "https://acct.queue.core.windows.net/"
// after
// ConnectionStrings:queues = "https://acct.queue.core.windows.net/myqueue"
// or in appsettings: "Aspire:Azure:Storage:Queues:queues": { "QueueName": "myqueue" }
builder.AddAzureQueueClient("queues");

Defensive patterns

Strategy: validation

Validate before calling

var settings = builder.Configuration.GetSection("Aspire:Azure:Storage:Queues");
var cs = builder.Configuration.GetConnectionString("queues");
var queueName = settings["QueueName"] ?? (cs?.Contains("myqueue") == true ? "myqueue" : null);
if (string.IsNullOrEmpty(queueName))
    throw new InvalidOperationException("QueueClient requires a queue name; set QueueName in config or use a full queue URL connection string.");

Try / catch

try { queueClient.SendMessageAsync("ping"); }
catch (InvalidOperationException ex) when (ex.Message.Contains("missing the queue name"))
{
    logger.LogError(ex, "Queue name missing for connection 'queues'.");
    throw;
}

Prevention

Use full queue URL connection strings (https://acct.queue.core.windows.net/myqueue) for AddAzureQueueClient.
Prefer AddAzureQueues when you need account-level access rather than a single queue.
Document required config keys per component in your service template.
Validate QueueName presence in integration tests before first send/receive.

When it happens

Trigger: Calling AddAzureQueueClient where the 'ConnectionStrings:{connectionName}' value is missing entirely, or present but lacking a 'QueueName' component, and settings.QueueName was not set via configuration or the configureSettings callback.

Common situations: Connection string in config contains only the account endpoint without the queue path (e.g. a plain service URI instead of a full queue URL); developer used the QueueServiceClient connection string with the QueueClient API; QueueName key misspelled in config section.

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

Appendix: source

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

            => settings.Credential;

        protected override bool GetMetricsEnabled(AzureStorageQueuesSettings settings)
            => false;

        protected override bool GetTracingEnabled(AzureStorageQueuesSettings settings)
            => !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)

View on GitHub (pinned to 25830f84bd)