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.

What it means

When FullyQualifiedNamespace is provided (no connection string), the event hub name must come from settings because a namespace alone doesn't identify a hub. If EventHubName is null/empty in that scenario, the component throws.

Solutions

  1. Set settings.EventHubName in the ConfigureSettings callback.
  2. Or add '"EventHubName": "<hub>"' under the '{configurationSectionName}' config section.
  3. Alternatively supply a full connection string containing EntityPath instead of FullyQualifiedNamespace.

Example fix

// before
builder.AddAzureEventHubConsumerClient("eh", settings => { settings.FullyQualifiedNamespace = "ns.servicebus.windows.net"; });
// after
builder.AddAzureEventHubConsumerClient("eh", settings => {
  settings.FullyQualifiedNamespace = "ns.servicebus.windows.net";
  settings.EventHubName = "orders";
});
Defensive patterns

Strategy: validation

Validate before calling

var cs = builder.Configuration["ConnectionStrings:eh"];
var hubName = builder.Configuration["EventHubs:EventHubName"];
if (string.IsNullOrEmpty(cs) && string.IsNullOrEmpty(hubName))
    throw new InvalidOperationException("Namespace-only configuration requires EventHubName.");

Try / catch

try { consumer = serviceProvider.GetRequiredService<EventHubConsumerClient>(); } catch (InvalidOperationException ex) when (ex.Message.Contains("EventHubName")) { logger.LogError(ex, "EventHubName required when using FullyQualifiedNamespace"); throw; }

Prevention

When it happens

Trigger: AddAzureEventHub* (EnsureConnectionStringOrNamespaceProvided) when settings.ConnectionString is empty, settings.FullyQualifiedNamespace is set, and settings.EventHubName is null/whitespace.

Common situations: Using Microsoft Entra ID authentication with only the namespace configured but forgetting to set EventHubName; '{configurationSectionName}:EventHubName' missing from appsettings.json; settings callback assigning EventHubName conditionally and the condition not firing.

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

Appendix: source

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

            {
                // 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)