microsoft/aspire · error · InvalidOperationException

A could not be configured. Please ensure that the…

Error message

A {typeof(TClient).Name} could not be configured. Please ensure that the ConnectionString or FullyQualifiedNamespace is well-formed.

What it means

EventHubsComponent sanitizes an Event Hubs namespace (derived from the connection string or FullyQualifiedNamespace) for use in names such as blob container/consumer identifiers. If parsing the connection string or namespace throws FormatException or IndexOutOfRangeException, the value is malformed and the component rethrows as an InvalidOperationException naming the client type.

Solutions

Copy the full Event Hubs connection string from the portal (SharedAccessPolicy connection string, format: Endpoint=sb://<ns>.servicebus.windows.net/;SharedAccessKeyName=...;SharedAccessKey=...).
If using FullyQualifiedNamespace instead, set it to '<namespace>.servicebus.windows.net' with no scheme or path.
Validate the connection string by constructing EventHubsConnectionStringProperties.Parse(connectionString) locally to see the exact parse failure.
Check for accidental inclusion of surrounding quotes or extra semicolons in configuration.

Example fix

// before
// ConnectionStrings:events = "sb://myns.servicebus.windows.net/"  (not a valid connection string)
// after
// ConnectionStrings:events = "Endpoint=sb://myns.servicebus.windows.net/;SharedAccessKeyName=RootManageSharedAccessKey;SharedAccessKey=..."
builder.AddAzureEventHubProducerClient("events", "hub");

Defensive patterns

Strategy: validation

Validate before calling

var cs = builder.Configuration["ConnectionStrings:eh"];
if (!string.IsNullOrEmpty(cs))
{
    try { var p = Azure.Messaging.EventHubs.EventHubsConnectionStringProperties.Parse(cs); _ = p.FullyQualifiedNamespace; }
    catch (Exception ex) { throw new InvalidOperationException($"Malformed Event Hubs connection string: {ex.Message}"); }
}

Try / catch

try { return serviceProvider.GetRequiredService<EventHubProducerClient>(); } catch (InvalidOperationException ex) when (ex.Message.Contains("well-formed")) { logger.LogError(ex, "Event Hubs connection string format is invalid"); throw; }

Prevention

Always copy the connection string directly from the portal without manual edits
Parse with EventHubsConnectionStringProperties in a startup health check
Prefer FullyQualifiedNamespace + credential to avoid connection-string parsing entirely
Watch for quotes/whitespace sneaking into config values from secret managers

When it happens

Trigger: GetNamespaceFromSettings throws when the ConnectionString is not a well-formed Event Hubs connection string (e.g. missing 'Endpoint=sb://...' part causing parsing errors) or FullyQualifiedNamespace is malformed, during any AddAzureEventHub* client registration.

Common situations: Connection string copied incorrectly (truncated, quotes included, wrong service's connection string such as a Storage or ServiceBus string); whitespace or invalid characters in FullyQualifiedNamespace; hand-edited config missing required segments.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of microsoft/aspire@25830f84bd (2026-09-16). Data as JSON: /api/errors/e83edcf58d618311. Report an issue: GitHub.

Appendix: source

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

            ns = string.IsNullOrWhiteSpace(settings.FullyQualifiedNamespace)
                ? EventHubsConnectionStringProperties.Parse(settings.ConnectionString).Endpoint.Host
                : new Uri(settings.FullyQualifiedNamespace).Host;

            // This is likely to be similar to {yournamespace}.servicebus.windows.net or {yournamespace}.servicebus.chinacloudapi.cn
            var serviceBusIndex = ns.IndexOf(".servicebus", StringComparison.OrdinalIgnoreCase);
            if (serviceBusIndex != -1)
            {
                ns = ns[..serviceBusIndex];
            }
            else
            {
                // sanitize the namespace if it's not a servicebus namespace
                ns = ns.Replace(".", "-");
            }
        }
        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.");
        }

View on GitHub (pinned to 25830f84bd)