HangfireIO/Hangfire · error · ArgumentException

At least one non-started thread should be created.

Error message

At least one non-started thread should be created.

What it means

Thrown by the BackgroundTaskScheduler constructor when the threadFactory returns null or an empty collection. The scheduler needs at least one dedicated thread to run its dispatch loop and to report MaximumConcurrencyLevel, so zero threads is unusable.

Source

Thrown at src/Hangfire.Core/Processing/BackgroundTaskScheduler.cs:125

            [CanBeNull] Action<Exception> exceptionHandler)
        {
            if (threadFactory == null) throw new ArgumentNullException(nameof(threadFactory));

            _exceptionHandler = exceptionHandler;
            _semaphore = new Semaphore(0, Int32.MaxValue);

            // Stopped event should always be the first in this array, see the DispatchLoop method.
            _waitHandles = new WaitHandle[] { _stopped, _semaphore };

#if !NETSTANDARD1_3
            AppDomainUnloadMonitor.EnsureInitialized();
#endif

            _threads = threadFactory(DispatchLoop)?.ToArray();

            if (_threads == null || _threads.Length == 0)
            {
                throw new ArgumentException("At least one non-started thread should be created.", nameof(threadFactory));
            }

            if (_threads.Any(static thread => thread == null || (thread.ThreadState & ThreadState.Unstarted) == 0))
            {
                throw new ArgumentException("All the threads should be non-null and in the ThreadState.Unstarted state.", nameof(threadFactory));
            }

            foreach (var thread in _threads)
            {
                thread.Start();
            }

            _ourThreadIds = new HashSet<int>(_threads.Select(static x => x.ManagedThreadId));
        }

        /// <inheritdoc />
        public override int MaximumConcurrencyLevel => _threads.Length;

View on GitHub (pinned to c236dd0f93)

Solutions

1. Ensure the factory returns at least one thread for any input.
2. If deriving count from config, clamp the count to >= 1 before building threads.
3. Default to Environment.ProcessorCount when the configured count is unavailable.

Example fix

// before
Func<ThreadStart, IEnumerable<Thread>> factory = start =>
    Enumerable.Range(0, threadCount).Where(i => false).Select(i => new Thread(start)); // empty

// after
var count = Math.Max(1, threadCount);
Func<ThreadStart, IEnumerable<Thread>> factory = start =>
    Enumerable.Range(0, count).Select(i => new Thread(start) { IsBackground = true });

Func<ThreadStart, IEnumerable<Thread>> factory = start =>
    Enumerable.Range(0, Math.Max(1, threadCount))
              .Select(i => new Thread(start) { IsBackground = true });
// ensure the factory never returns an empty collection

try { var s = new BackgroundTaskScheduler(factory, handler); }
catch (ArgumentException ex) when (ex.ParamName == nameof(threadFactory))
{ /* rebuild factory with a guaranteed non-empty count */ }

When it happens

Trigger: A threadFactory that returns null, returns an empty enumerable, or whose Where/filter removes all threads. Distinct from the null-thread case (error 173) — here the collection itself is empty.

Common situations: A factory that filters threads by a condition that matches none; a factory that returns null on a fast-path; a threadCount of zero feeding a factory that yields nothing.

Related errors

• threadFactory
• All the threads should be non-null and in the ThreadState.Un
• threadCount
• All the threads should be non-null and in the ThreadState.Un
• maxConcurrency

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