HangfireIO/Hangfire · critical · InvalidOperationException

Please add a NuGet package reference to either 'Microsoft.Da

Error message

Please add a NuGet package reference to either 'Microsoft.Data.SqlClient' or 'System.Data.SqlClient' in your application project. Hangfire.SqlServer supports both providers but let the consumer decide which one should be used.

What it means

The SqlServerStorageOptions.SqlClientFactory getter threw because no SQL client NuGet package is referenced by the consuming project. Hangfire.SqlServer does not depend on either Microsoft.Data.SqlClient or System.Data.SqlClient directly; the consumer must add one. The getter lazily resolves the factory only when first accessed.

Source

Thrown at src/Hangfire.SqlServer/SqlServerStorageOptions.cs:200

        public int DeleteExpiredBatchSize { get; set; }

        /// <summary>
        /// Gets or sets whether to enable experimental feature of transactional acknowledge of completed
        /// background jobs. In this case there will be less requests sent to SQL Server and better handling
        /// of data loss when asynchronous replication is used. But additional blocking on the JobQueue table
        /// is expected, since transaction commit requires an explicit Commit request to be sent. 
        /// </summary>
        public bool UseTransactionalAcknowledge { get; set; }

        /// <summary>
        /// Gets or sets the <see cref="DbProviderFactory"/> for creating <c>SqlConnection</c> instances.
        /// Defaults to either <c>System.Data.SqlClient.SqlClientFactory.Instance</c> or
        /// <c>Microsoft.Data.SqlClient.SqlClientFactory</c> depending on which package reference exists
        /// on the consuming project.
        /// </summary>
        public DbProviderFactory SqlClientFactory
        {
            get => _sqlClientFactory ?? throw new InvalidOperationException("Please add a NuGet package reference to either 'Microsoft.Data.SqlClient' or 'System.Data.SqlClient' in your application project. " +
                                                                            "Hangfire.SqlServer supports both providers but let the consumer decide which one should be used.");
            set => _sqlClientFactory = value ?? throw new ArgumentNullException(nameof(value));
        }

        /// <summary>
        /// Gets or sets whether to try automatically query for the current schema on application start
        /// and enable <see cref="UseIgnoreDupKeyOption"/>, <see cref="DeleteExpiredBatchSize"/> and
        /// <see cref="DisableGlobalLocks"/> options depending on the current schema version. When storage
        /// is inaccessible on startup, default values will be used for those options.
        /// </summary>
        public bool TryAutoDetectSchemaDependentOptions { get; set; }

        /// <summary>
        /// Gets or sets a default queue provider that will be used when no special provider was
        /// registered for a particular queue.
        /// </summary>
        public IPersistentJobQueueProvider DefaultQueueProvider { get; set; }

View on GitHub (pinned to c236dd0f93)

Solutions

1. Add a NuGet reference to Microsoft.Data.SqlClient (recommended for new projects) to your application project.
2. Alternatively, add System.Data.SqlClient if you need legacy compatibility.
3. Rebuild and confirm the package appears in the project's dependencies before configuring Hangfire storage.

Example fix

// before — only Hangfire.SqlServer referenced, throws on storage init
dotnet add package Hangfire.SqlServer
// after — add a SqlClient package
dotnet add package Microsoft.Data.SqlClient
// then:
config.UseSqlServerStorage("Server=.;Database=Hangfire;Integrated Security=true;TrustServerCertificate=true");

// At startup, verify a SqlClient package is referenced:
Type factoryType = Type.GetType("Microsoft.Data.SqlClient.SqlClientFactory, Microsoft.Data.SqlClient")
    ?? Type.GetType("System.Data.SqlClient.SqlClientFactory, System.Data.SqlClient");

if (factoryType == null)
    throw new InvalidOperationException("Add Microsoft.Data.SqlClient or System.Data.SqlClient NuGet package.");

When it happens

Trigger: Adding only the Hangfire.SqlServer package to a project without also adding Microsoft.Data.SqlClient or System.Data.SqlClient; the factory is accessed (during storage initialization or connection creation) before any client package is installed.

Common situations: New project setup missing the SqlClient dependency; CI build restoring only Hangfire packages; upgrading Hangfire.SqlServer after the client package was removed.

Related errors

• The provider factory ({_options.SqlClientFactory}) returned
• configuration
• value
• Attempts value must be equal or greater than zero.
• DelaysInSeconds value must be an array of non-negative numbe

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