dotnet/reactive · error · ArgumentOutOfRangeException

period (Parameter 'period')

Error message

period (Parameter 'period')

What it means

NewThreadScheduler.SchedulePeriodic<TState>(state, period, action) throws ArgumentOutOfRangeException when period is less than TimeSpan.Zero. A periodic schedule needs a non-negative interval; a negative period is meaningless and would break the underlying Periodic timer setup.

Solutions

  1. Clamp the period before scheduling: 'if (period < TimeSpan.Zero) period = TimeSpan.Zero;'.
  2. Use TimeSpan.FromMilliseconds(Timeout.Infinite) semantics only where the API supports it; otherwise pick a positive default.
  3. Validate configured intervals at startup and fail fast with a clear message.
  4. Recompute deadline-derived intervals with Math.Max(TimeSpan.Zero, deadline - now).

Example fix

// before
var period = deadline - DateTime.UtcNow;
scheduler.SchedulePeriodic(state, period, Tick);
// after
var period = deadline - DateTime.UtcNow;
if (period < TimeSpan.Zero) period = TimeSpan.Zero;
scheduler.SchedulePeriodic(state, period, Tick);
Defensive patterns

Strategy: validation

Validate before calling

if (period < TimeSpan.Zero)
    throw new ArgumentOutOfRangeException(nameof(period));

Type guard

bool IsValidPeriod(TimeSpan period) => period >= TimeSpan.Zero;

Try / catch

try
{
    scheduler.SchedulePeriodic(state, period, action);
}
catch (ArgumentOutOfRangeException ex) when (ex.ParamName == "period")
{
    period = TimeSpan.Zero; // or a sane default, then reschedule
}

Prevention

When it happens

Trigger: Calling SchedulePeriodic with a negative TimeSpan, e.g. computed as 'endTime - now' after the deadline passed, or from configuration where an interval parses as negative.

Common situations: Polling intervals derived from a deadline already in the past; misparsed config strings ('-00:00:05'); unit tests passing TimeSpan.MinValue as a sentinel; arithmetic like TimeSpan.FromMilliseconds(-1) from metrics.

Related errors

AI-assisted analysis of dotnet/reactive@94b5d5ab91 (2026-09-15). Data as JSON: /api/errors/7831c0486b6f3984. Report an issue: GitHub.

Appendix: source

Thrown at Rx.NET/Source/src/System.Reactive/Concurrency/NewThreadScheduler.cs:111

            return d;
        }

        /// <summary>
        /// Schedules a periodic piece of work by creating a new thread that goes to sleep when work has been dispatched and wakes up again at the next periodic due time.
        /// </summary>
        /// <typeparam name="TState">The type of the state passed to the scheduled action.</typeparam>
        /// <param name="state">Initial state passed to the action upon the first iteration.</param>
        /// <param name="period">Period for running the work periodically.</param>
        /// <param name="action">Action to be executed, potentially updating the state.</param>
        /// <returns>The disposable object used to cancel the scheduled recurring action (best effort).</returns>
        /// <exception cref="ArgumentNullException"><paramref name="action"/> is <c>null</c>.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="period"/> is less than <see cref="TimeSpan.Zero"/>.</exception>
        public IDisposable SchedulePeriodic<TState>(TState state, TimeSpan period, Func<TState, TState> action)
        {
            if (period < TimeSpan.Zero)
            {
                throw new ArgumentOutOfRangeException(nameof(period));
            }

            if (action == null)
            {
                throw new ArgumentNullException(nameof(action));
            }

            var periodic = new Periodic<TState>(state, period, action);

            var thread = _threadFactory(periodic.Run);
            thread.Start();

            return periodic;
        }

        private sealed class Periodic<TState> : IDisposable
        {
            private readonly IStopwatch _stopwatch;

View on GitHub (pinned to 94b5d5ab91)