HangfireIO/Hangfire · error · ArgumentNullException

options

Error message

options

What it means

Thrown by the BackgroundExecution constructor (internal) when the BackgroundExecutionOptions argument is null. Options carry the warning/error thresholds and retry-delay function used throughout the execution loop, so a null options object would NRE on every state transition.

Source

Thrown at src/Hangfire.Core/Processing/BackgroundExecution.cs:55

        private readonly ManualResetEvent _stopped = new ManualResetEvent(false);
        private Stopwatch _faultedSince;
        private Stopwatch _failedSince;
        private Stopwatch _lastException;
        private int _exceptionsCount;

        private CancellationToken _stopToken;
        private readonly BackgroundExecutionOptions _options;
        private readonly ILog _logger;

        private readonly Stopwatch _createdAt;
        private Stopwatch _stoppedAt;
        private CancellationTokenRegistration _stopRegistration;

        private volatile bool _disposed;

        public BackgroundExecution([NotNull] BackgroundExecutionOptions options, CancellationToken stopToken)
        {
            _options = options ?? throw new ArgumentNullException(nameof(options));

            _logger = LogProvider.GetLogger(GetType());
            _createdAt = Stopwatch.StartNew();

            _stopToken = stopToken;

            _stopRegistration = _stopToken.Register(SetStoppedAt);

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

        public bool StopRequested => _disposed || _stopToken.IsCancellationRequested;

        public void Run(Action<Guid, object> callback, object state)
        {
            if (callback == null) throw new ArgumentNullException(nameof(callback));

View on GitHub (pinned to c236dd0f93)

Solutions

1. Pass a non-null BackgroundExecutionOptions — create one with `new BackgroundExecutionOptions()` if defaults are acceptable.
2. Guard at the call site: fail fast with a descriptive message if options is null before constructing.
3. Ensure the code that owns options lifecycle initializes it before the execution.

Example fix

// before
var execution = new BackgroundExecution(null, stopToken);

// after
var options = options ?? new BackgroundExecutionOptions();
var execution = new BackgroundExecution(options, stopToken);

var options = configuredOptions ?? new BackgroundExecutionOptions();

When it happens

Trigger: Constructing BackgroundExecution with options == null. Reached when server wiring passes null instead of a BackgroundExecutionOptions instance.

Common situations: A factory method that builds execution returned null options; a code path that constructs BackgroundExecution before initializing its options; refactoring that dropped the options argument.

Related errors

• execution
• taskScheduler
• callback
• value
• waitHandle

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