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.ExpiryTimeout)} must be greater than zero.

What it means

Thrown by the ADO.NET streaming options validator when ExpiryTimeout is negative. ExpiryTimeout is how long before a message is considered expired and moved to dead letters regardless of attempt count. The check is `< TimeSpan.Zero`, so zero is accepted though the message says 'greater than zero'.

Source

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

        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)
        {
            throw new OrleansConfigurationException($"Invalid {nameof(AdoNetStreamOptions)} values for ADO.NET Streaming Provider '{name}': {nameof(options.EvictionInterval)} must be greater than zero.");
        }

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

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

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

View on GitHub (pinned to fca799fa70)

Solutions

  1. Set options.ExpiryTimeout to a positive TimeSpan greater than VisibilityTimeout (e.g. the default 10 minutes).
  2. Check the appsettings.json string format and sign.
  3. Use TimeSpan.FromMinutes to set it explicitly and keep it > VisibilityTimeout.

Example fix

// before
builder.AddAdoNetStreams("ads", o =>
{
    o.ExpiryTimeout = TimeSpan.FromMinutes(-10);
});

// after
builder.AddAdoNetStreams("ads", o =>
{
    o.ExpiryTimeout = TimeSpan.FromMinutes(10);
});
Defensive patterns

Strategy: validation

Validate before calling

static void CheckExpiryTimeout(AdoNetStreamOptions o)
{
    if (o.ExpiryTimeout < TimeSpan.Zero)
        throw new InvalidOperationException("AdoNetStreamOptions.ExpiryTimeout must be non-negative and greater than VisibilityTimeout.");
}

Prevention

When it happens

Trigger: ValidateConfiguration() runs on AdoNetStreamOptions with ExpiryTimeout < TimeSpan.Zero. The default is 10 minutes, so this only fires if it was explicitly set negative.

Common situations: Setting ExpiryTimeout to a negative TimeSpan; mistyping a duration string in config; unit confusion when computing the value.

Understand the failure class

Related errors

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