microsoft/aspire · error · InvalidOperationException

A QueueServiceClient could not be configured. Ensure valid…

Error message

A QueueServiceClient 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

Aspire's Azure Storage Queues client registration requires a way to construct a QueueServiceClient. This error is thrown when, at service resolution time, neither a connection string nor a ServiceUri was resolved from the connection name or the component's configuration section, so no client can be created.

Solutions

Add a 'ConnectionStrings:{connectionName}' value (storage account connection string or service URI) to appsettings.json or user secrets.
If running under the Aspire AppHost, ensure the project references the Azure Storage Queues hosting resource so the connection is injected at run time.
Alternatively set 'ConnectionString' or 'ServiceUri' under the 'Aspire:Azure:Storage:Queues' configuration section.
Verify the connectionName passed to AddAzureQueues matches the configured key exactly (case-sensitive lookup).

Example fix

// before
builder.AddAzureQueuesClient("queues"); // no 'queues' connection defined
// after (appsettings.json)
// { "ConnectionStrings": { "queues": "https://mystorageaccount.queue.core.windows.net/" } }
builder.AddAzureQueuesClient("queues");

Defensive patterns

Strategy: validation

Validate before calling

var cs = builder.Configuration.GetConnectionString("queues");
var section = builder.Configuration.GetSection("Aspire:Azure:Storage:Queues");
if (string.IsNullOrEmpty(cs) && section["ServiceUri"] is null && section["ConnectionString"] is null)
    throw new InvalidOperationException("Configure ConnectionStrings:queues or Aspire:Azure:Storage:Queues before calling AddAzureQueuesClient.");

Try / catch

try { /* first resolve of QueueServiceClient */ }
catch (InvalidOperationException ex) when (ex.Message.Contains("QueueServiceClient could not be configured"))
{
    logger.LogError(ex, "Azure Storage Queues connection info missing; check ConnectionStrings:queues.");
    throw;
}

Prevention

Register storage resources in the AppHost and use WithReference so connection strings are injected automatically.
Keep connection names consistent between AppHost and consuming project.
Add a startup config sanity check in non-Aspire environments.
Store local overrides in user secrets, not appsettings.json.

When it happens

Trigger: Calling AddAzureQueues/AddKeyedAzureQueues with a connectionName that has no 'ConnectionStrings:{connectionName}' entry and no 'ConnectionString' or 'ServiceUri' key in the '{configurationSectionName}' config section (e.g. Aspire:Azure:Storage:Queues).

Common situations: Connection string not set in appsettings.json or user secrets; running outside Aspire AppHost without connection-string injection; typo in connection name; using a keyed variant with a name that was never registered; config section renamed after a package upgrade.

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

Appendix: source

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

    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentException.ThrowIfNullOrEmpty(name);

        new StorageQueueComponent().AddClient(builder, DefaultConfigSectionName, configureSettings, configureClientBuilder, connectionName: name, serviceKey: name);
    }

    private sealed class StorageQueuesComponent : AzureComponent<AzureStorageQueuesSettings, QueueServiceClient, QueueClientOptions>
    {
        protected override IAzureClientBuilder<QueueServiceClient, QueueClientOptions> AddClient(
            AzureClientFactoryBuilder azureFactoryBuilder, AzureStorageQueuesSettings settings, string connectionName,
            string configurationSectionName)
        {
            return ((IAzureClientFactoryBuilderWithCredential)azureFactoryBuilder).RegisterClientFactory<QueueServiceClient, QueueClientOptions>((options, cred) =>
            {
                var connectionString = settings.ConnectionString;
                if (string.IsNullOrEmpty(connectionString) && settings.ServiceUri is null)
                {
                    throw new InvalidOperationException($"A QueueServiceClient could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify a 'ConnectionString' or 'ServiceUri' in the '{configurationSectionName}' configuration section.");
                }

                return !string.IsNullOrEmpty(connectionString)
                    ? new QueueServiceClient(connectionString, options)
                    : cred is not null
                        ? new QueueServiceClient(settings.ServiceUri, cred, options)
                        : new QueueServiceClient(settings.ServiceUri, options);
            }, requiresCredential: false);
        }

        protected override void BindClientOptionsToConfiguration(IAzureClientBuilder<QueueServiceClient, 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
        }

        protected override void BindSettingsToConfiguration(AzureStorageQueuesSettings settings, IConfiguration configuration)

View on GitHub (pinned to 25830f84bd)