dotnet/orleans · error · OrleansConfigurationException

Invalid {nameof(AdoNetStreamOptions)} values for ADO.NET Str

Error message

Invalid {nameof(AdoNetStreamOptions)} values for ADO.NET Streaming Provider '{name}': {nameof(options.Invariant)} is required.

What it means

Thrown by the ADO.NET streaming options validator when Invariant is null or whitespace. AdoNetStreamOptions.Invariant defaults to null, so it must be set explicitly so the provider knows which database driver and query dialect to use for the stream queues.

Source

Thrown at src/AdoNet/Orleans.Streaming.AdoNet/AdoNetStreamOptionsValidator.cs:15

using static System.String;

namespace Orleans.Configuration;

/// <summary>
/// Validates <see cref="AdoNetStreamOptions"/> configuration.
/// </summary>
public class AdoNetStreamOptionsValidator(AdoNetStreamOptions options, string name) : IConfigurationValidator
{
    /// <inheritdoc />
    public void ValidateConfiguration()
    {
        if (IsNullOrWhiteSpace(options.Invariant))
        {
            throw new OrleansConfigurationException($"Invalid {nameof(AdoNetStreamOptions)} values for ADO.NET Streaming Provider '{name}': {nameof(options.Invariant)} is required.");
        }

        if (IsNullOrWhiteSpace(options.ConnectionString) == (options.DataSource is null))
        {
            throw new OrleansConfigurationException($"Invalid {nameof(AdoNetStreamOptions)} values for ADO.NET Streaming Provider '{name}': configure exactly one of {nameof(options.ConnectionString)} or {nameof(options.DataSource)}.");
        }

        if (options.MaxAttempts < 0)
        {
            throw new OrleansConfigurationException($"Invalid {nameof(AdoNetStreamOptions)} values for ADO.NET Streaming Provider '{name}': {nameof(options.MaxAttempts)} must be greater than zero.");
        }

        if (options.VisibilityTimeout < TimeSpan.Zero)
        {
            throw new OrleansConfigurationException($"Invalid {nameof(AdoNetStreamOptions)} values for ADO.NET Streaming Provider '{name}': {nameof(options.VisibilityTimeout)} must be greater than zero.");
        }

        if (options.EvictionInterval < TimeSpan.Zero)

View on GitHub (pinned to fca799fa70)

Solutions

Set options.Invariant = AdoNetInvariants.InvariantNameSqlServer (or the relevant driver) for the provider.
Use the AddAdoNetStreams overload with a configure delegate that sets Invariant.
Ensure the stream provider section in appsettings.json includes an Invariant key.

Example fix

// before
builder.AddAdoNetStreams("ads", o =>
{
    o.ConnectionString = "Server=.;Database=Orleans;";
});

// after
builder.AddAdoNetStreams("ads", o =>
{
    o.Invariant = AdoNetInvariants.InvariantNameSqlServer;
    o.ConnectionString = "Server=.;Database=Orleans;";
});

Defensive patterns

Strategy: validation

Validate before calling

static void CheckStreamInvariant(AdoNetStreamOptions o)
{
    if (string.IsNullOrWhiteSpace(o.Invariant))
        throw new InvalidOperationException("AdoNetStreamOptions.Invariant is required.");
}

Prevention

Set Invariant explicitly per stream provider — it has no default.
Reference AdoNetInvariants constants.
Add a config test asserting each provider's Invariant is non-blank.

When it happens

Trigger: ValidateConfiguration() runs on AdoNetStreamOptions with a blank Invariant. Triggered at host startup when AddAdoNetStreams is registered without setting Invariant for the named provider.

Common situations: Adding an ADO.NET stream provider with only a connection string; assuming Invariant is inherited from clustering/storage; copy-paste config that omits the Invariant key.

Related errors

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