HangfireIO/Hangfire · critical · ArgumentNullException

storage

Error message

storage

What it means

This ArgumentNullException("storage") is thrown by the most detailed BackgroundJobServer constructor (the [Obsolete] one taking options, storage, additionalProcesses, filterProvider, activator, factory, performer, stateChanger) when the supplied JobStorage is null. The simpler constructors forward to JobStorage.Current when storage is omitted, so reaching this throw means either the advanced constructor was called explicitly with a null storage, or JobStorage.Current was null and was forwarded in.

Source

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

#pragma warning disable 618
            : 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. Call GlobalConfiguration.Configuration.UseMemoryStorage() (or a real storage) before constructing BackgroundJobServer.
2. Pass a non-null JobStorage explicitly to the constructor.
3. In ASP.NET Core, use services.AddHangfire(cfg => cfg.UseXxxStorage(...)) and AddHangfireServer() so storage is wired by the integration.
4. Verify the connection string / storage config is present in the target environment.

Example fix

// before
var server = new BackgroundJobServer(); // JobStorage.Current is null

// after
GlobalConfiguration.Configuration.UseSqlServerStorage("HangfireDb");
var server = new BackgroundJobServer();

if (JobStorage.Current is null)
    throw new InvalidOperationException("JobStorage is not configured; call GlobalConfiguration.Configuration.UseXxxStorage first.");
var server = new BackgroundJobServer();

static bool IsStorageConfigured() => JobStorage.Current is not null;

try { var server = new BackgroundJobServer(options, storage); }
catch (ArgumentNullException ex) when (ex.ParamName == "storage") { throw new InvalidOperationException("Hangfire storage not configured at startup.", ex); }

When it happens

Trigger: Calling `new BackgroundJobServer(options)` or `new BackgroundJobServer(options, storage)` while JobStorage.Current has never been set and storage is null; or calling the advanced constructor explicitly with a null storage argument.

Common situations: Startup ordering bug: BackgroundJobServer is constructed before GlobalConfiguration.Configuration.UseXXXStorage(...) runs; ASP.NET Core app that creates the server manually instead of via AddHangfireServer and never sets JobStorage.Current; environment-specific storage config (connection string) missing in a deployment; tests that spin up a server without configuring a storage (e.g. MemoryStorage).

Related errors

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

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