dotnet/orleans · error · OrleansConfigurationException

No IStreamQueueCheckpointer is configured with PersistentStr

Error message

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

What it means

Thrown by KinesisStreamCheckpointerConfigurationValidator.ValidateConfiguration at silo startup when no IStreamQueueCheckpointerFactory is registered for the Kinesis stream provider name. The Kinesis streaming provider needs a checkpointer to track per-shard sequence positions; without one the provider cannot resume correctly, so Orleans fails fast.

Source

Thrown at src/AWS/Orleans.Streaming.Kinesis/Hosting/SiloKinesisStreamConfigurator.cs:78

                DynamoDBStreamQueueCheckpointerFactory.CreateFactory,
                options => configureOptions?.Invoke(options));
            this.ConfigureDelegate(services => services.AddTransient<IConfigurationValidator>(
                sp => new DynamoDBStreamQueueCheckpointerOptionsValidator(
                    sp.GetOptionsByName<DynamoDBStreamQueueCheckpointerOptions>(Name),
                    Name)));
            return this;
        }
    }

    internal sealed class KinesisStreamCheckpointerConfigurationValidator(
        IServiceProvider services,
        string name) : IConfigurationValidator
    {
        public void ValidateConfiguration()
        {
            if (services.GetKeyedService<IStreamQueueCheckpointerFactory>(name) is null)
            {
                throw new OrleansConfigurationException(
                    $"No IStreamQueueCheckpointer is configured with PersistentStreamProvider {name}. Please configure one.");
            }
        }
    }
}

View on GitHub (pinned to fca799fa70)

Solutions

Register an IStreamQueueCheckpointerFactory for the same provider name when configuring the Kinesis stream (e.g. via the stream configurator's checkpointer hook or AddKinesisStream with a checkpointer configured).
Ensure the keyed service name exactly matches the stream provider name passed to the configurator.
Check the Kinesis sample's hosting code for the checkpointer registration and copy that block.

Example fix

// before: stream configured, no checkpointer
silo.AddKinesisStreams("kinesis", b => b.ConfigureStream(providerName)); // validator throws

// after: register a checkpointer factory for the provider name
services.AddKeyedSingleton<IStreamQueueCheckpointerFactory>(providerName, ...);

Defensive patterns

Strategy: validation

Validate before calling

// Ensure a checkpointer factory is registered for the provider name
if (services.GetKeyedService<IStreamQueueCheckpointerFactory>(name) is null)
    throw new InvalidOperationException($"Register an IStreamQueueCheckpointerFactory for '{name}'.");

Type guard

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

Try / catch

null

Prevention

Register an IStreamQueueCheckpointerFactory keyed by the exact provider name.
Match the keyed-service name to the stream provider name passed to the configurator.
Copy the checkpointer registration block from the Kinesis sample when setting up streaming.

When it happens

Trigger: Configuring a Kinesis persistent stream provider (AddKinesisStream / UseKinesisStream) without also registering a checkpointer factory for that provider name via GetKeyedService<IStreamQueueCheckpointerFactory>(name).

Common situations: Following only the stream-config half of a Kinesis sample and skipping the checkpointer setup; renaming the provider without re-registering the checkpointer under the new name; upgrading Orleans and the checkpointer registration API changed.

Related errors

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