HangfireIO/Hangfire · error · InvalidOperationException

The provider factory ({_options.SqlClientFactory}) returned

Error message

The provider factory ({_options.SqlClientFactory}) returned a null DbConnection.

What it means

The configured DbProviderFactory's CreateConnection method returned null when Hangfire tried to create a new SQL Server connection. This is an InvalidOperationException thrown from DefaultConnectionFactory, meaning the SqlClientFactory implementation is broken or misconfigured.

Source

Thrown at src/Hangfire.SqlServer/SqlServerStorage.cs:434

            }
        }

        internal bool IsExistingConnection(IDbConnection connection)
        {
            return connection != null && ReferenceEquals(connection, _existingConnection);
        }

        internal void ReleaseConnection(IDbConnection connection)
        {
            if (connection != null && !IsExistingConnection(connection))
            {
                connection.Dispose();
            }
        }
        
        private DbConnection DefaultConnectionFactory()
        {
            var connection = _options.SqlClientFactory.CreateConnection() ?? throw new InvalidOperationException($"The provider factory ({_options.SqlClientFactory}) returned a null DbConnection.");
            connection.ConnectionString = _connectionString;
            return connection;
        }

        private static bool IsRunningOnWindows()
        {
#if !NETSTANDARD1_3
            return Environment.OSVersion.Platform == PlatformID.Win32NT;
#else
            return System.Runtime.InteropServices.RuntimeInformation.IsOSPlatform(System.Runtime.InteropServices.OSPlatform.Windows);
#endif
        }

        private void Initialize()
        {
            _escapedSchemaName = _options.SchemaName.Replace("]", "]]");

            if (_options.PrepareSchemaIfNecessary)

View on GitHub (pinned to c236dd0f93)

Solutions

1. Do not override SqlServerStorageOptions.SqlClientFactory unless necessary; let Hangfire auto-detect based on the referenced package.
2. If overriding, ensure the factory's CreateConnection returns a non-null DbConnection instance.
3. Verify that exactly one SqlClient NuGet package (Microsoft.Data.SqlClient or System.Data.SqlClient) is referenced and not corrupted.

Example fix

// before — custom factory returns null
options.SqlClientFactory = new MyBrokenFactory();
// after — use a real factory or remove the override
options.SqlClientFactory = Microsoft.Data.SqlClient.SqlClientFactory.Instance;
// or simply don't set it at all (auto-detection)

var factory = options.SqlClientFactory;
using var testConn = factory.CreateConnection()
    ?? throw new InvalidOperationException("Configured SqlClientFactory returns null from CreateConnection.");
testConn.ConnectionString = connectionString;
// If this succeeds, storage initialization will too.

When it happens

Trigger: SqlServerStorageOptions.SqlClientFactory is set to a custom or incorrectly configured DbProviderFactory whose CreateCommand/CreateConnection returns null; a corrupted or incompatible SqlClient package installation.

Common situations: Manually assigning a wrong factory type to SqlClientFactory; assembly loading conflicts between Microsoft.Data.SqlClient and System.Data.SqlClient; a custom factory wrapper that returns null instead of a connection.

Related errors

• Please add a NuGet package reference to either 'Microsoft.Da
• value
• Attempts value must be equal or greater than zero.
• DelaysInSeconds value must be an array of non-negative numbe
• client

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