HangfireIO/Hangfire · error · ArgumentOutOfRangeException

StopTimeout must be either equal to or less than {Int32.MaxV

Error message

StopTimeout must be either equal to or less than {Int32.MaxValue} milliseconds and non-negative or infinite

What it means

This ArgumentOutOfRangeException("value", "StopTimeout must be either equal to or less than Int32.MaxValue milliseconds and non-negative or infinite") is thrown by the StopTimeout setter of BackgroundJobServerOptions. The setter rejects any value that is negative (unless it equals Timeout.InfiniteTimeSpan) or whose total milliseconds exceed Int32.MaxValue. StopTimeout bounds how long the processing server waits for currently-running jobs to finish when stopping.

Source

Thrown at src/Hangfire.Core/BackgroundJobServerOptions.cs:97

        {
            get { return _queues; }
            set
            {
                if (value == null) throw new ArgumentNullException(nameof(value));
                if (value.Length == 0) throw new ArgumentException("You should specify at least one queue to listen.", nameof(value));

                _queues = value;
            }
        }

        public TimeSpan StopTimeout
        {
            get => _stopTimeout;
            set
            {
                if ((value < TimeSpan.Zero && value != Timeout.InfiniteTimeSpan) || value.TotalMilliseconds > Int32.MaxValue)
                {
                    throw new ArgumentOutOfRangeException(nameof(value), $"StopTimeout must be either equal to or less than {Int32.MaxValue} milliseconds and non-negative or infinite");
                }
                _stopTimeout = value;
            }
        }

        public TimeSpan ShutdownTimeout
        {
            get { return _shutdownTimeout; }
            set
            {
                if ((value < TimeSpan.Zero && value != Timeout.InfiniteTimeSpan) || value.TotalMilliseconds > Int32.MaxValue)
                {
                    throw new ArgumentOutOfRangeException(nameof(value), $"ShutdownTimeout must be either equal to or less than {Int32.MaxValue} milliseconds and non-negative or infinite");
                }
                _shutdownTimeout = value;
            }
        }

View on GitHub (pinned to c236dd0f93)

Solutions

1. Use a non-negative TimeSpan within Int32.MaxValue milliseconds (about 24.8 days), or Timeout.InfiniteTimeSpan.
2. Clamp the bound value: options.StopTimeout = TimeSpan.FromMilliseconds(Math.Clamp(ms, 0, int.MaxValue)).
3. Use the default (BackgroundProcessingServerOptions.DefaultStopTimeout) by not setting the property.
4. Validate the configured timeout at startup.

Example fix

// before
options.StopTimeout = TimeSpan.FromSeconds(-5);

// after
options.StopTimeout = TimeSpan.FromSeconds(30); // or leave default

TimeSpan SanitizeTimeout(TimeSpan ts) =>
    ts == Timeout.InfiniteTimeSpan || (ts >= TimeSpan.Zero && ts.TotalMilliseconds <= int.MaxValue)
        ? ts : BackgroundProcessingServerOptions.DefaultStopTimeout;
options.StopTimeout = SanitizeTimeout(parsed);

static bool IsValidTimeout(TimeSpan ts) => ts == Timeout.InfiniteTimeSpan || (ts >= TimeSpan.Zero && ts.TotalMilliseconds <= int.MaxValue);

try { options.StopTimeout = parsed; }
catch (ArgumentOutOfRangeException) { options.StopTimeout = BackgroundProcessingServerOptions.DefaultStopTimeout; }

When it happens

Trigger: Assigning options.StopTimeout = TimeSpan.FromSeconds(-1) (negative, not infinite); options.StopTimeout = TimeSpan.FromMilliseconds(int.MaxValue + 1.0) (over the limit); binding a config value parsed from a negative or huge number.

Common situations: Config typos (negative timeout); unit mismatches (treating a value as seconds but it is milliseconds, producing an overflow); binding TimeSpan.MaxValue from config; tests that probe boundary values.

Understand the failure class

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

Related errors

• ShutdownTimeout must be either equal to or less than {Int32.
• SchedulePollingInterval must be non-negative and either equa
• WorkerCount property value should be positive.
• HeartbeatInterval must be either non-negative and equal to o
• ServerCheckInterval must be either non-negative and equal to

AI-assisted analysis of HangfireIO/Hangfire@c236dd0f93 (2026-08-13). Data as JSON: /api/errors/5883a0c7f7e2c2fd. Report an issue: GitHub.