microsoft/aspire · error · InvalidOperationException

A could not be configured. Ensure valid connection…

Error message

A {typeof(TClient).Name} could not be configured. Ensure valid connection information was provided in 'ConnectionStrings:{connectionName}' or specify a 'ConnectionString' or 'FullyQualifiedNamespace' in the '{configurationSectionName}' configuration section.

What it means

EnsureConnectionStringOrNamespaceProvided requires that at least one of ConnectionString or FullyQualifiedNamespace is present in the bound EventHubs settings. When both are missing there is no endpoint to connect to, so the component throws before creating the client factory registration.

Solutions

Add the Event Hubs connection string under 'ConnectionStrings:{connectionName}' in appsettings.json or as environment variable ConnectionStrings__<name>.
Or set FullyQualifiedNamespace in the '{configurationSectionName}' section (plus a credential) instead of a connection string.
If using Aspire, add .WithReference(eventHubs) in the AppHost so the connection string is injected automatically.
Verify the connectionName/configurationSectionName arguments match your configuration keys.

Example fix

// before
builder.AddAzureEventHubProducerClient("eh", settings => { settings.EventHubName = "hub"; }); // no connection info
// after (appsettings.json)
// { "ConnectionStrings": { "eh": "Endpoint=sb://ns.servicebus.windows.net/;..." } }
builder.AddAzureEventHubProducerClient("eh", settings => { settings.EventHubName = "hub"; });

Defensive patterns

Strategy: validation

Validate before calling

var section = builder.Configuration.GetSection("ConnectionStrings:eh");
var fqns = builder.Configuration["EventHubs:FullyQualifiedNamespace"];
if (string.IsNullOrEmpty(section.Value) && string.IsNullOrEmpty(fqns))
    throw new InvalidOperationException("Configure ConnectionStrings:eh or EventHubs:FullyQualifiedNamespace before AddAzureEventHub*.");

Type guard

bool hasEventHubsConnection = !string.IsNullOrWhiteSpace(config["ConnectionStrings:eh"]) || !string.IsNullOrWhiteSpace(config["EventHubs:FullyQualifiedNamespace"]);

Try / catch

try { hubClient = serviceProvider.GetRequiredService<EventHubProducerClient>(); } catch (InvalidOperationException ex) when (ex.Message.Contains("could not be configured")) { logger.LogCritical(ex, "Event Hubs connection info missing"); throw; }

Prevention

Use WithReference in the AppHost to inject connection strings automatically
Assert required config keys at startup (fail fast before serving traffic)
Match configuration section names exactly with the component registration names

When it happens

Trigger: Calling AddAzureEventHubProducerClient/ConsumerClient/EventHubClient (AddClient path invoking EnsureConnectionStringOrNamespaceProvided) when settings.ConnectionString is null/empty and settings.FullyQualifiedNamespace is null/empty.

Common situations: No 'ConnectionStrings:{connectionName}' key in configuration; config section '{configurationSectionName}:FullyQualifiedNamespace' not set; running outside the Aspire AppHost so the connection string was never injected; key name mismatch between the AddAzure... call and config.

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

Appendix: source

Thrown at src/Components/Aspire.Azure.Messaging.EventHubs/EventHubsComponent.cs:126

        }
        catch (Exception ex) when (ex is FormatException or IndexOutOfRangeException)
        {
            throw new InvalidOperationException(
                $"A {typeof(TClient).Name} could not be configured. Please ensure that the ConnectionString or FullyQualifiedNamespace is well-formed.");
        }

        return ns;
    }

    protected static void EnsureConnectionStringOrNamespaceProvided(AzureMessagingEventHubsSettings settings,
        string connectionName, string configurationSectionName)
    {
        var connectionString = settings.ConnectionString;

        // Are we missing both connection string and namespace? throw.
        if (string.IsNullOrEmpty(connectionString) && string.IsNullOrEmpty(settings.FullyQualifiedNamespace))
        {
            throw new InvalidOperationException(
                $"A {typeof(TClient).Name} could not be configured. Ensure valid connection information was provided in " +
                $"'ConnectionStrings:{connectionName}' or specify a 'ConnectionString' or 'FullyQualifiedNamespace' in the '{configurationSectionName}' configuration section.");
        }

        // If we have a connection string, ensure there's an EntityPath if settings.EventHubName is missing
        if (!string.IsNullOrWhiteSpace(settings.ConnectionString))
        {
            // We have a connection string -- do we have an EventHubName?
            if (string.IsNullOrWhiteSpace(settings.EventHubName))
            {
                // look for EntityPath
                var props = EventHubsConnectionStringProperties.Parse(connectionString);

                // if EntityPath is missing, throw
                if (string.IsNullOrWhiteSpace(props.EventHubName))
                {
                    throw new InvalidOperationException(
                        $"A {typeof(TClient).Name} could not be configured. Ensure a valid EventHubName was provided in " +

View on GitHub (pinned to 25830f84bd)