microsoft/aspire · error · InvalidOperationException

A PartitionReceiver could not be configured. Ensure a valid…

Error message

A PartitionReceiver could not be configured. Ensure a valid PartitionId was provided in the '{configurationSectionName}' configuration section.

What it means

PartitionReceiverClientComponent builds a PartitionReceiver, which by definition must target a specific Event Hub partition. After validating connection/namespace info, AddClient checks settings.PartitionId and throws if it's empty, since a PartitionReceiver cannot be created without it.

Solutions

Set settings.PartitionId in the ConfigureSettings callback, e.g. settings => settings.PartitionId = "0".
Or add '"PartitionId": "0"' under the '{configurationSectionName}' config section.
If you don't actually need a fixed partition, use AddAzureEventHubConsumerClient (EventProcessorClient/EventHubConsumerClient) instead of the PartitionReceiver component.

Example fix

// before
builder.AddAzurePartitionReceiverClient("eh", settings => { settings.EventHubName = "orders"; }); // missing PartitionId
// after
builder.AddAzurePartitionReceiverClient("eh", settings => { settings.EventHubName = "orders"; settings.PartitionId = "0"; });

Defensive patterns

Strategy: validation

Validate before calling

var partitionId = builder.Configuration["PartitionReceiver:PartitionId"];
if (string.IsNullOrEmpty(partitionId) || !int.TryParse(partitionId, out _))
    throw new InvalidOperationException("PartitionId must be set (e.g. \"0\") before AddAzurePartitionReceiverClient.");

Try / catch

try { receiver = serviceProvider.GetRequiredService<PartitionReceiver>(); } catch (InvalidOperationException ex) when (ex.Message.Contains("PartitionId")) { logger.LogError(ex, "PartitionId missing for PartitionReceiver"); throw; }

Prevention

Set PartitionId explicitly in the settings callback at registration
If partitions are dynamic, use the EventHubConsumerClient/EventProcessorClient components instead
Validate partition ids exist on the hub (GetEventHubProperties) at startup

When it happens

Trigger: AddAzurePartitionReceiverClient (AddClient) when settings.PartitionId is null/empty — PartitionId absent from both the settings callback and the '{configurationSectionName}' configuration section.

Common situations: Developer uses the partition receiver component but forgets that unlike regular consumers, a partition id is mandatory; copying the setup for AddAzureEventHubConsumerClient (which doesn't need PartitionId); config key 'PartitionId' missing from appsettings.json; intending dynamic partition assignment when PartitionReceiver is the wrong API.

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

Appendix: source

Thrown at src/Components/Aspire.Azure.Messaging.EventHubs/PartitionReceiverClientComponent.cs:40

    }

    protected override void BindSettingsToConfiguration(AzureMessagingEventHubsPartitionReceiverSettings settings, IConfiguration config)
    {
        config.Bind(settings);
    }

    protected override IAzureClientBuilder<PartitionReceiver, PartitionReceiverOptions> AddClient(
        AzureClientFactoryBuilder azureFactoryBuilder, AzureMessagingEventHubsPartitionReceiverSettings settings,
        string connectionName, string configurationSectionName)
    {
        return ((IAzureClientFactoryBuilderWithCredential)azureFactoryBuilder).RegisterClientFactory<PartitionReceiver, PartitionReceiverOptions>((options, cred) =>
        {
            // ensure that the connection string or namespace+eventhubname is provided
            EnsureConnectionStringOrNamespaceProvided(settings, connectionName, configurationSectionName);

            if (string.IsNullOrEmpty(settings.PartitionId))
            {
                throw new InvalidOperationException(
                    $"A PartitionReceiver could not be configured. Ensure a valid PartitionId was provided in the '{configurationSectionName}' configuration section.");
            }

            options.Identifier ??= GenerateClientIdentifier(settings.EventHubName, settings.ConsumerGroup);

            if (string.IsNullOrEmpty(settings.ConnectionString))
            {
                return new PartitionReceiver(
                    settings.ConsumerGroup ?? EventHubConsumerClient.DefaultConsumerGroupName,
                    settings.PartitionId,
                    settings.EventPosition,
                    settings.FullyQualifiedNamespace,
                    settings.EventHubName,
                    cred, options);
            }

            if (string.IsNullOrEmpty(settings.EventHubName))
            {

View on GitHub (pinned to 25830f84bd)