dotnet/orleans · critical · OrleansConfigurationException

No IStreamQueueCheckpointer is configured with PersistentStr

Error message

No IStreamQueueCheckpointer is configured with PersistentStreamProvider {this.name}. Please configure one.

What it means

Thrown by StreamCheckpointerConfigurationValidator.ValidateConfiguration at startup when no keyed IStreamQueueCheckpointerFactory is registered for the PersistentStreamProvider name. The EventHub adapter requires a checkpointer to persist read offsets.

Source

Thrown at src/Azure/Orleans.Streaming.EventHubs/Providers/Streams/EventHub/EventHubStreamOptions.cs:206

                throw new OrleansConfigurationException($"{nameof(EventHubOptions)} on stream provider {this.name} is invalid. {nameof(EventHubOptions.EventHubName)} is invalid");
            }
        }
    }

    public class StreamCheckpointerConfigurationValidator : IConfigurationValidator
    {
        private readonly IServiceProvider services;
        private readonly string name;
        public StreamCheckpointerConfigurationValidator(IServiceProvider services, string name)
        {
            this.services = services;
            this.name = name;
        }
        public void ValidateConfiguration()
        {
            var checkpointerFactory = services.GetKeyedService<IStreamQueueCheckpointerFactory>(this.name);
            if (checkpointerFactory == null)
                throw new OrleansConfigurationException($"No IStreamQueueCheckpointer is configured with PersistentStreamProvider {this.name}. Please configure one.");
        }
    }

    public class EventHubReceiverOptions
    {
        /// <summary>
        /// Optional parameter that configures the receiver prefetch count.
        /// </summary>
        public int? PrefetchCount { get; set; }
        /// <summary>
        /// In cases where no checkpoint is found, this indicates if service should read from the most recent data, or from the beginning of a partition.
        /// </summary>
        public bool StartFromNow { get; set; } = DEFAULT_START_FROM_NOW;
        private const bool DEFAULT_START_FROM_NOW = true;
    }

    public class EventHubStreamCachePressureOptions
    {

View on GitHub (pinned to fca799fa70)

Solutions

1. Register a checkpointer factory for the provider name, e.g. config.AddAzureTableCheckpointer(...) inside the stream configuration.
2. Ensure the keyed service name matches the PersistentStreamProvider name exactly.
3. For dev/test, use AddGrainBasedCheckpointer as a lighter alternative.

Example fix

// before
siloBuilder.AddEventHubStreams("EH", c =>
{
    c.ConfigureEventHubConnection(...);
    // no checkpointer registered
});

// after
siloBuilder.AddEventHubStreams("EH", c =>
{
    c.ConfigureEventHubConnection(...);
    c.UseAzureTableCheckpointer(ob => ob.Configure(o =>
    {
        o.TableName = "checkpoints";
        o.ConnectionString = azureStorageConn;
    }));
});

var cp = services.GetKeyedService<IStreamQueueCheckpointerFactory>(providerName);
if (cp is null) throw new OrleansConfigurationException("Register a checkpointer for " + providerName);

static bool HasCheckpointer(IServiceProvider sp, string name) =>
    sp.GetKeyedService<IStreamQueueCheckpointerFactory>(name) is not null;

When it happens

Trigger: Configuring a PersistentStreamProvider with the EventHub adapter but not registering the checkpointer (e.g. missing AddAzureTableCheckpointer / AddGrainBasedCheckpointer) for that provider name.

Common situations: Following a receiver-only setup sample that omits checkpointing; migrating to a version where the checkpointer must be registered explicitly; keying the checkpointer under a different name than the stream provider.

Related errors

• Azure Event Hub connection not configured for stream provide
• EventHubOptions on stream provider {this.name} is invalid. E
• EventHubOptions on stream provider {this.name} is invalid. E
• No credentials specified. Use the {options.GetType().Name}.C
• connection

AI-assisted analysis of dotnet/orleans@fca799fa70 (2026-08-13). Data as JSON: /api/errors/714c753f5f4bf443. Report an issue: GitHub.