HangfireIO/Hangfire · error · ArgumentOutOfRangeException

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

Error message

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

What it means

This ArgumentOutOfRangeException("value", "ServerTimeout must be either non-negative and equal to or less than ServerWatchdog.MaxServerTimeout.Hours hours") is thrown by the ServerTimeout setter of BackgroundJobServerOptions. The value must be non-negative and not exceed ServerWatchdog.MaxServerTimeout. ServerTimeout defines how long a server can go without a heartbeat before the watchdog considers it dead and removes it.

Source

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

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

        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 CancellationCheckInterval { get; set; }

        [Obsolete("Please use `ServerTimeout` or `ServerCheckInterval` options instead. Will be removed in 2.0.0.")]
        public ServerWatchdogOptions ServerWatchdogOptions { get; set; }

        [CanBeNull]
        public IJobFilterProvider FilterProvider { get; set; }

        [CanBeNull]
        public JobActivator Activator { get; set; }

View on GitHub (pinned to c236dd0f93)

Solutions

1. Use a non-negative TimeSpan no greater than ServerWatchdog.MaxServerTimeout (default ServerWatchdog.DefaultServerTimeout).
2. Clamp the bound value into the legal range.
3. Leave the property unset to keep the default.
4. Validate the configured value at startup.

Example fix

// before
options.ServerTimeout = TimeSpan.FromHours(48); // exceeds MaxServerTimeout

// after
options.ServerTimeout = ServerWatchdog.DefaultServerTimeout; // safe default

TimeSpan Sanitize(TimeSpan ts) =>
    ts >= TimeSpan.Zero && ts <= ServerWatchdog.MaxServerTimeout ? ts : ServerWatchdog.DefaultServerTimeout;
options.ServerTimeout = Sanitize(parsed);

static bool IsValid(TimeSpan ts) => ts >= TimeSpan.Zero && ts <= ServerWatchdog.MaxServerTimeout;

try { options.ServerTimeout = parsed; }
catch (ArgumentOutOfRangeException) { options.ServerTimeout = ServerWatchdog.DefaultServerTimeout; }

When it happens

Trigger: Assigning a negative ServerTimeout; assigning a value greater than ServerWatchdog.MaxServerTimeout; binding an out-of-range value from configuration.

Common situations: Raising ServerTimeout to tolerate slow environments beyond the watchdog ceiling; config typos producing negative values; unit confusion; binding a misconfigured large value.

Understand the failure class

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

Related errors

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

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