HangfireIO/Hangfire · error · ArgumentOutOfRangeException

ServerTimeout must be either non-negative and equal to or…

Error message

ServerTimeout must be either non-negative and equal to or less than {ServerWatchdog.MaxServerTimeout.Hours} hours

What it means

Thrown as ArgumentOutOfRangeException by the obsolete ServerWatchdogOptions.ServerTimeout setter when the supplied TimeSpan is negative or exceeds ServerWatchdog.MaxServerTimeout (24 hours). The watchdog uses this timeout to consider a server dead if it stops heartbeating; an out-of-range value would either mark healthy servers as dead (too small) or never reap stuck servers (too large), so the setter rejects it at line 41.

Solutions

Use the non-obsolete BackgroundJobServerOptions.ServerTimeout instead, which enforces the same bounds (0..24h) and is the supported configuration surface.
Clamp or validate the configured TimeSpan to the [TimeSpan.Zero, TimeSpan.FromHours(24)] range before assignment.
If reading from configuration, parse explicitly (TimeSpan.Parse) and log the resolved value to catch unit or magnitude errors early.

Example fix

// before
watchdog.ServerTimeout = TimeSpan.FromHours(25); // throws

// after
var timeout = TimeSpan.FromMinutes(cfg.TimeoutMinutes);
serverOptions.ServerTimeout = timeout > ServerWatchdog.MaxServerTimeout
    ? ServerWatchdog.MaxServerTimeout : timeout;

Defensive patterns

Strategy: validation

Validate before calling

var timeout = TimeSpan.FromMinutes(cfg.TimeoutMinutes);
if (timeout < TimeSpan.Zero || timeout > ServerWatchdog.MaxServerTimeout)
    throw new ArgumentOutOfRangeException(nameof(timeout));
options.ServerTimeout = timeout;

Prevention

Use BackgroundJobServerOptions.ServerTimeout (non-obsolete) instead of ServerWatchdogOptions.
Clamp configured TimeSpans to [Zero, MaxServerTimeout] and log the resolved value.
Parse config with explicit units (TimeSpan.FromMinutes/FromSeconds) to avoid magnitude errors.

When it happens

Trigger: Setting options.ServerTimeout to a value where value < TimeSpan.Zero or value > TimeSpan.FromHours(24). E.g. options.ServerTimeout = TimeSpan.FromHours(25), or a negative TimeSpan from a miscomputed configuration value.

Common situations: A configuration value (e.g. from appsettings) parsed as hours/minutes and multiplied incorrectly producing >24h; a negative TimeSpan from a subtraction that underflows; copying a ServerCheckInterval value into ServerTimeout by mistake where intervals differ; deployment across machines with clock or locale quirks in TimeSpan parsing.

Understand the failure class

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

Related errors

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

Appendix: source

Thrown at src/Hangfire.Core/Obsolete/ServerWatchdogOptions.cs:41

    public class ServerWatchdogOptions
    {
        private TimeSpan _serverTimeout;
        private TimeSpan _checkInterval;

        public ServerWatchdogOptions()
        {
            ServerTimeout = ServerWatchdog.DefaultServerTimeout;
            CheckInterval = ServerWatchdog.DefaultCheckInterval;
        }

        public TimeSpan ServerTimeout
        {
            get { return _serverTimeout; }
            set
            {
                if (value < TimeSpan.Zero || value > ServerWatchdog.MaxServerTimeout)
                {
                    throw new ArgumentOutOfRangeException(nameof(value), $"ServerTimeout must be either non-negative and equal to or less than {ServerWatchdog.MaxServerTimeout.Hours} hours");
                }

                _serverTimeout = value;
            }
        }

        public TimeSpan CheckInterval
        {
            get { return _checkInterval; }
            set
            {
                if (value < TimeSpan.Zero || value > ServerWatchdog.MaxServerCheckInterval)
                {
                    throw new ArgumentOutOfRangeException(nameof(value), $"CheckInterval must be either non-negative and equal to or less than {ServerWatchdog.MaxServerCheckInterval.Hours} hours");

                };
                _checkInterval = value;
            }

View on GitHub (pinned to c236dd0f93)