microsoft/aspire · error · InvalidOperationException

A could not be configured. Ensure a valid EventHubName was…

Error message

A {typeof(TClient).Name} could not be configured. Ensure a valid EventHubName was provided in the '{configurationSectionName}' configuration section, or include an EntityPath in the ConnectionString.

What it means

When a connection string is supplied but no EventHubName in settings, the component parses the connection string looking for an EntityPath that names the hub. If the EntityPath is also absent, Aspire cannot determine which event hub to use and throws.

Solutions

Set settings.EventHubName in the settings callback or the '{configurationSectionName}:EventHubName' config key.
Or use an entity-scoped connection string that includes 'EntityPath=<hub-name>'.
Confirm the EventHubName config key is read (section name matches) if relying on configuration rather than code.

Example fix

// before
builder.AddAzureEventHubProducerClient("eh"); // connection string has no EntityPath
// after
builder.AddAzureEventHubProducerClient("eh", settings => { settings.EventHubName = "orders"; });
// or use connection string with ;EntityPath=orders

Defensive patterns

Strategy: validation

Validate before calling

var hubName = builder.Configuration["EventHubs:EventHubName"];
var cs = builder.Configuration["ConnectionStrings:eh"];
var hasEntityPath = cs?.Contains("EntityPath=") == true;
if (string.IsNullOrEmpty(hubName) && !hasEntityPath)
    throw new InvalidOperationException("Set EventHubName or use a connection string with EntityPath.");

Try / catch

try { client = serviceProvider.GetRequiredService<EventHubProducerClient>(); } catch (InvalidOperationException ex) when (ex.Message.Contains("EventHubName")) { logger.LogError(ex, "Event hub name missing"); throw; }

Prevention

Always set EventHubName explicitly in the settings callback
Prefer namespace-level connection string + explicit EventHubName over EntityPath strings
Document required config keys for each environment

When it happens

Trigger: AddAzureEventHub* (via EnsureConnectionStringOrNamespaceProvided) with settings.EventHubName null/empty and a namespace-level connection string without 'EntityPath=<hub>' (EventHubsConnectionStringProperties.Parse returns empty EventHubName).

Common situations: Copying the Event Hubs namespace-level connection string (from the namespace SharedAccessPolicy) which lacks EntityPath, then forgetting to set EventHubName; typos in the settings callback so EventHubName isn't actually assigned; config key for EventHubName misspelled.

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

Appendix: source

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

        {
            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 " +
                        $"the '{configurationSectionName}' configuration section, or include an EntityPath in the ConnectionString.");
                }
                // The connection string has an EventHubName, but we'll set this anyway so the health check can use it
                settings.EventHubName = props.EventHubName;
            }
        }
        // If we have a namespace and no connection string, ensure there's an EventHubName
        else if (!string.IsNullOrWhiteSpace(settings.FullyQualifiedNamespace) && string.IsNullOrWhiteSpace(settings.EventHubName))
        {
            throw new InvalidOperationException(
                $"A {typeof(TClient).Name} could not be configured. Ensure a valid EventHubName was provided in " +
                $"the '{configurationSectionName}' configuration section.");
        }
    }
}

View on GitHub (pinned to 25830f84bd)