dotnet/orleans · error · OrleansConfigurationException

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

Q: What causes "Invalid {nameof(AdoNetStreamOptions)} values for ADO.NET Streaming Provider '{name}': {nameof(options.DeadLetterEvictionTimeout)} must be greater than zero." in dotnet/orleans?

Set options.DeadLetterEvictionTimeout to a positive TimeSpan greater than ExpiryTimeout (e.g. the default 7 days).

Error message

Invalid {nameof(AdoNetStreamOptions)} values for ADO.NET Streaming Provider '{name}': {nameof(options.DeadLetterEvictionTimeout)} must be greater than zero.

What it means

Thrown by the ADO.NET streaming options validator when DeadLetterEvictionTimeout is negative. This timeout is how long a failed message lives in the dead-letter table before deletion. 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:45

        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

Set options.DeadLetterEvictionTimeout to a positive TimeSpan greater than ExpiryTimeout (e.g. the default 7 days).
Check the appsettings.json string format and sign.
Use TimeSpan.FromDays to set it explicitly.

Example fix

// before
builder.AddAdoNetStreams("ads", o =>
{
    o.DeadLetterEvictionTimeout = TimeSpan.FromDays(-7);
});

// after
builder.AddAdoNetStreams("ads", o =>
{
    o.DeadLetterEvictionTimeout = TimeSpan.FromDays(7);
});

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Keep DeadLetterEvictionTimeout positive and larger than ExpiryTimeout (default 7 days).
Use TimeSpan.FromDays with explicit positive values.
Add a config test asserting the ordering of stream eviction timeouts.

When it happens

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

Common situations: Setting DeadLetterEvictionTimeout to a negative TimeSpan; mistyping a duration string in config; computing the value with a sign error.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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