HangfireIO/Hangfire · error · ArgumentOutOfRangeException

ShutdownTimeout must be either equal to or less than {Int32.

Error message

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

What it means

This ArgumentOutOfRangeException("value", "ShutdownTimeout must be either equal to or less than Int32.MaxValue milliseconds and non-negative or infinite") is thrown by the ShutdownTimeout setter of BackgroundJobServerOptions. Same rule as StopTimeout: reject negative (unless exactly Timeout.InfiniteTimeSpan) or values over Int32.MaxValue total milliseconds. ShutdownTimeout bounds how long the server waits during a full shutdown before abandoning jobs.

Source

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

            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;
            }
        }

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

                _schedulePollingInterval = value;
            }
        }

View on GitHub (pinned to c236dd0f93)

Solutions

1. Use Timeout.InfiniteTimeSpan to wait indefinitely, or a non-negative TimeSpan within Int32.MaxValue ms.
2. Clamp the bound value into the legal range.
3. Leave the property unset to use the default (BackgroundProcessingServer.DefaultShutdownTimeout).
4. Validate the configured value at startup.

Example fix

// before
options.ShutdownTimeout = TimeSpan.MaxValue; // TotalMilliseconds over Int32.MaxValue

// after
options.ShutdownTimeout = Timeout.InfiniteTimeSpan; // wait forever, legal

TimeSpan SanitizeTimeout(TimeSpan ts) =>
    ts == Timeout.InfiniteTimeSpan || (ts >= TimeSpan.Zero && ts.TotalMilliseconds <= int.MaxValue)
        ? ts : BackgroundProcessingServer.DefaultShutdownTimeout;
options.ShutdownTimeout = SanitizeTimeout(parsed);

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

try { options.ShutdownTimeout = parsed; }
catch (ArgumentOutOfRangeException) { options.ShutdownTimeout = BackgroundProcessingServer.DefaultShutdownTimeout; }

When it happens

Trigger: Assigning a negative ShutdownTimeout that is not Timeout.InfiniteTimeSpan; assigning a TimeSpan whose TotalMilliseconds exceeds Int32.MaxValue; binding an out-of-range value from configuration.

Common situations: Config typos producing negative values; unit confusion (seconds vs milliseconds) causing overflow; binding TimeSpan.MaxValue; intending to wait forever but writing TimeSpan.MaxValue instead of Timeout.InfiniteTimeSpan.

Understand the failure class

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

Related errors

• StopTimeout must be either equal to or less than {Int32.MaxV
• 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/e22ef8f9831a92a2. Report an issue: GitHub.