HangfireIO/Hangfire · error · ArgumentOutOfRangeException

WorkerCount property value should be positive.

Error message

WorkerCount property value should be positive.

What it means

This ArgumentOutOfRangeException("value", "WorkerCount property value should be positive.") is thrown by the WorkerCount setter of BackgroundJobServerOptions when the value is less than or equal to zero. WorkerCount controls how many Worker instances process jobs; a non-positive count would create no workers, so Hangfire rejects it at assignment time. The default is min(Environment.ProcessorCount * 5, 20).

Source

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

            TimeZoneResolver = null;
            TaskScheduler = TaskScheduler.Default;
        }
        
        public string ServerName { get; set; }

        /// <summary>
        /// Gets or sets whether storage instance will include only <see cref="Worker"/> and required
        /// <see cref="ServerWatchdog"/> and <see cref="ServerJobCancellationWatcher"/> processes. No
        /// storage-related processes or recurring/delayed job schedulers will be included.
        /// </summary>
        public bool IsLightweightServer { get; set; }

        public int WorkerCount
        {
            get { return _workerCount; }
            set
            {
                if (value <= 0) throw new ArgumentOutOfRangeException(nameof(value), "WorkerCount property value should be positive.");

                _workerCount = value;
            }
        }

        public string[] Queues
        {
            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

View on GitHub (pinned to c236dd0f93)

Solutions

1. Set WorkerCount to a positive integer (1 is the minimum valid value).
2. Coerce bound config: options.WorkerCount = Math.Max(1, parsedValue).
3. Leave WorkerCount unset to use the default (min(ProcessorCount*5, 20)).
4. Validate the config value at startup before assigning it to the options.

Example fix

// before
options.WorkerCount = int.Parse(config["Workers"]); // empty -> 0

// after
options.WorkerCount = Math.Max(1, int.Parse(config["Workers"]));

int parsed = int.TryParse(config["Workers"], out var w) ? w : new BackgroundJobServerOptions().WorkerCount;
options.WorkerCount = Math.Max(1, parsed);

static bool IsValidWorkerCount(int value) => value > 0;

try { options.WorkerCount = value; }
catch (ArgumentOutOfRangeException) { options.WorkerCount = new BackgroundJobServerOptions().WorkerCount; }

When it happens

Trigger: Assigning options.WorkerCount = 0 or a negative number, e.g. from a misbound configuration value, a division that rounds to zero, or Environment.ProcessorCount-derived math that produced zero.

Common situations: Binding WorkerCount from a config section that is missing/empty (parsed as 0); computing WorkerCount from a percentage or CPU metric that returned 0; deployment where a scaling setting was set to 0 to disable workers instead of using a different mechanism; test fixtures that default numeric fields to 0.

Related errors

• StopTimeout must be either equal to or less than {Int32.MaxV
• ShutdownTimeout must be either equal to or less than {Int32.
• SchedulePollingInterval must be non-negative and either equa
• 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/9eb4f1a76823dd41. Report an issue: GitHub.