HangfireIO/Hangfire · error · ArgumentOutOfRangeException

ServerCheckInterval must be either non-negative and equal to

Error message

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

What it means

This ArgumentOutOfRangeException("value", "ServerCheckInterval must be either non-negative and equal to or less than ServerWatchdog.MaxServerCheckInterval.Hours hours") is thrown by the ServerCheckInterval setter of BackgroundJobServerOptions. The value must be non-negative and not exceed ServerWatchdog.MaxServerCheckInterval. ServerCheckInterval controls how often the watchdog itself scans for dead servers.

Source

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

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

        public TimeSpan ServerCheckInterval
        {
            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;

            }

View on GitHub (pinned to c236dd0f93)

Solutions

1. Use a non-negative TimeSpan no greater than ServerWatchdog.MaxServerCheckInterval (default ServerWatchdog.DefaultCheckInterval).
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.ServerCheckInterval = TimeSpan.FromHours(10); // exceeds MaxServerCheckInterval

// after
options.ServerCheckInterval = ServerWatchdog.DefaultCheckInterval; // safe default

TimeSpan Sanitize(TimeSpan ts) =>
    ts >= TimeSpan.Zero && ts <= ServerWatchdog.MaxServerCheckInterval ? ts : ServerWatchdog.DefaultCheckInterval;
options.ServerCheckInterval = Sanitize(parsed);

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

try { options.ServerCheckInterval = parsed; }
catch (ArgumentOutOfRangeException) { options.ServerCheckInterval = ServerWatchdog.DefaultCheckInterval; }

When it happens

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

Common situations: Tuning watchdog behavior and exceeding the allowed maximum; config typos; unit confusion; binding a huge value from a misconfigured section.

Related errors

• HeartbeatInterval must be either non-negative and equal to o
• ServerTimeout must be either non-negative and equal to or le
• 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/0cb058d8e3af8f07. Report an issue: GitHub.