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.VisibilityTimeout)} must be greater than zero." in dotnet/orleans?

Set options.VisibilityTimeout to a positive TimeSpan (e.g. the default 1 minute).

Error message

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

What it means

Thrown by the ADO.NET streaming options validator when VisibilityTimeout is negative. VisibilityTimeout controls how long a message stays invisible to other consumers after dequeue. The check is `< TimeSpan.Zero`, so zero is accepted though the message says 'greater than zero' — zero would cause immediate re-delivery contention.

Source

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

    {
        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)
        {
            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)

View on GitHub (pinned to fca799fa70)

Solutions

Set options.VisibilityTimeout to a positive TimeSpan (e.g. the default 1 minute).
Validate the config string format (e.g. "00:01:00") in appsettings.json.
Use TimeSpan.FromSeconds/FromMinutes to avoid tick/millisecond confusion.

Example fix

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

// after
builder.AddAdoNetStreams("ads", o =>
{
    o.VisibilityTimeout = TimeSpan.FromMinutes(2);
});

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Use TimeSpan.FromMinutes/FromSeconds with a positive value.
Validate duration config strings with TimeSpan.Parse in a config test.
Avoid computing TimeSpans from raw ticks to prevent sign errors.

When it happens

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

Common situations: Setting VisibilityTimeout = TimeSpan.FromMinutes(-1) by mistake; a config parser producing a negative TimeSpan from a malformed string; unit confusion (ticks vs. seconds).

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/065637ecda315907. Report an issue: GitHub.