HangfireIO/Hangfire · error · ArgumentNullException

options

Error message

options

What it means

This ArgumentNullException("options") is thrown by the detailed BackgroundJobServer constructor when the BackgroundJobServerOptions argument is null. BackgroundJobServer requires an options instance to configure WorkerCount, Queues, timeouts and intervals; passing null prevents the server from configuring its worker pool and processes. The throw fires before _options is assigned or any process is built.

Source

Thrown at src/Hangfire.Core/BackgroundJobServer.cs:101

            : this(options, storage, additionalProcesses, null, null, null, null, null)
#pragma warning restore 618
        {
        }

        [Obsolete("Create your own BackgroundJobServer-like type and pass custom services to it. This constructor will be removed in 2.0.0.")]
        [EditorBrowsable(EditorBrowsableState.Advanced)]
        public BackgroundJobServer(
            [NotNull] BackgroundJobServerOptions options,
            [NotNull] JobStorage storage,
            [NotNull] IEnumerable<IBackgroundProcess> additionalProcesses,
            [CanBeNull] IJobFilterProvider filterProvider,
            [CanBeNull] JobActivator activator,
            [CanBeNull] IBackgroundJobFactory factory,
            [CanBeNull] IBackgroundJobPerformer performer,
            [CanBeNull] IBackgroundJobStateChanger stateChanger)
        {
            if (storage == null) throw new ArgumentNullException(nameof(storage));
            if (options == null) throw new ArgumentNullException(nameof(options));
            if (additionalProcesses == null) throw new ArgumentNullException(nameof(additionalProcesses));

            _options = options;

            var processes = new List<IBackgroundProcessDispatcherBuilder>();
            processes.AddRange(GetRequiredProcesses(filterProvider, activator, factory, performer, stateChanger));
            processes.AddRange(additionalProcesses.Select(static x => x.UseBackgroundPool(1)));

            var properties = new Dictionary<string, object>
            {
                { "Queues", options.Queues },
                { "WorkerCount", options.WorkerCount }
            };

            _logger.Info($"Starting Hangfire Server using job storage: '{storage}'");

            storage.WriteOptionsToLog(_logger);

View on GitHub (pinned to c236dd0f93)

Solutions

1. Pass a non-null BackgroundJobServerOptions (use `new BackgroundJobServerOptions()` for defaults).
2. Register BackgroundJobServerOptions in DI or bind it from IConfiguration.
3. Prefer the parameterless BackgroundJobServer() constructor which supplies default options.
4. Guard at the call site: `options ?? new BackgroundJobServerOptions()`.

Example fix

// before
var server = new BackgroundJobServer(null, storage);

// after
var server = new BackgroundJobServer(new BackgroundJobServerOptions { WorkerCount = 10 }, storage);

var options = new BackgroundJobServerOptions();
var server = new BackgroundJobServer(options, storage);

static bool IsOptionsValid(BackgroundJobServerOptions options) => options is not null;

try { var server = new BackgroundJobServer(options, storage); }
catch (ArgumentNullException ex) when (ex.ParamName == "options") { throw new InvalidOperationException("BackgroundJobServerOptions was not provided.", ex); }

When it happens

Trigger: Calling the advanced constructor (or one of the two-argument overloads) with options set to null; e.g. new BackgroundJobServer(null, storage) or resolving BackgroundJobServerOptions as null from DI.

Common situations: DI container does not register BackgroundJobServerOptions (it is not registered automatically); manually constructing the server and forgetting `new BackgroundJobServerOptions()`; conditional construction where a config section binds to null; refactor that dropped the options argument.

Related errors

• storage
• factory
• performer
• value
• WorkerCount property value should be positive.

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