microsoft/aspire · error · InvalidOperationException

A BlobServiceClient could not be configured. Ensure valid…

Error message

A BlobServiceClient 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 Blob Storage integration throws this when neither a ConnectionString nor a ServiceUri is configured for BlobServiceClient. The client requires one of the two to reach the storage account; the library validates this up-front and throws a descriptive InvalidOperationException instead of an SDK error.

Solutions

Add a connection string: "ConnectionStrings": { "blobs": "<storage connection string>" } or an endpoint-style value
Set ServiceUri in config: "Aspire:Azure:Storage:Blobs": { "ServiceUri": "https://<account>.blob.core.windows.net/" }
In the AppHost call builder.AddAzureBlobStorage("blobs") and .WithReference(storage) in the project
Verify the connectionName string exactly matches the ConnectionStrings key

Example fix

// before
builder.AddAzureBlobServiceClient("storage"); // no 'storage' key in ConnectionStrings
// after (AppHost)
var storage = builder.AddAzureStorage("storage");
// project: builder.AddAzureBlobServiceClient("storage").WithReference(storage);

Defensive patterns

Strategy: validation

Validate before calling

if (builder.Configuration.GetConnectionString("blobs") is null &&
    builder.Configuration["Aspire:Azure:Storage:Blobs:ServiceUri"] is null)
    throw new InvalidOperationException("Provide ConnectionStrings:blobs or a ServiceUri for Blob Storage.");

Prevention

Use WithReference from the AppHost to inject connection strings
Match resource name to connectionName argument exactly
Keep user secrets in sync with the connection names used in code

When it happens

Trigger: Calling builder.AddAzureBlobServiceClient(connectionName) where 'ConnectionStrings:<connectionName>' does not exist and 'Aspire:Azure:Storage:Blobs' has no ConnectionString or ServiceUri key.

Common situations: Connection name mismatch between the AppHost resource name and the AddAzureBlobServiceClient argument; running locally without user secrets; storage resource not referenced via WithReference so no connection string was injected.

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

Appendix: source

Thrown at src/Components/Aspire.Azure.Storage.Blobs/AspireBlobStorageExtensions.BlobStorageComponent.cs:30

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Diagnostics.HealthChecks;

namespace Microsoft.Extensions.Hosting;

partial class AspireBlobStorageExtensions
{
    private sealed class BlobStorageComponent : AzureComponent<AzureStorageBlobsSettings, BlobServiceClient, BlobClientOptions>
    {
        protected override IAzureClientBuilder<BlobServiceClient, BlobClientOptions> AddClient(
            AzureClientFactoryBuilder azureFactoryBuilder, AzureStorageBlobsSettings settings, string connectionName,
            string configurationSectionName)
        {
            return ((IAzureClientFactoryBuilderWithCredential)azureFactoryBuilder).RegisterClientFactory<BlobServiceClient, BlobClientOptions>((options, cred) =>
            {
                var connectionString = settings.ConnectionString;
                if (string.IsNullOrEmpty(connectionString) && settings.ServiceUri is null)
                {
                    throw new InvalidOperationException($"A BlobServiceClient 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 BlobServiceClient(connectionString, options) :
                    cred is not null ? new BlobServiceClient(settings.ServiceUri, cred, options) :
                    new BlobServiceClient(settings.ServiceUri, options);
            }, requiresCredential: false);
        }

        protected override void BindClientOptionsToConfiguration(IAzureClientBuilder<BlobServiceClient, BlobClientOptions> 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(AzureStorageBlobsSettings settings, IConfiguration configuration)
        {
            configuration.Bind(settings);

View on GitHub (pinned to 25830f84bd)