{"record":{"id":"80b67fa3b731835e","repo":"HangfireIO/Hangfire","slug":"the-provider-factory-options-sqlclientfactory","errorCode":null,"errorMessage":"The provider factory ({_options.SqlClientFactory}) returned a null DbConnection.","messagePattern":"The provider factory \\((.+?)\\) returned a null DbConnection\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/Hangfire.SqlServer/SqlServerStorage.cs","lineNumber":434,"sourceCode":"            }\n        }\n\n        internal bool IsExistingConnection(IDbConnection connection)\n        {\n            return connection != null && ReferenceEquals(connection, _existingConnection);\n        }\n\n        internal void ReleaseConnection(IDbConnection connection)\n        {\n            if (connection != null && !IsExistingConnection(connection))\n            {\n                connection.Dispose();\n            }\n        }\n        \n        private DbConnection DefaultConnectionFactory()\n        {\n            var connection = _options.SqlClientFactory.CreateConnection() ?? throw new InvalidOperationException($\"The provider factory ({_options.SqlClientFactory}) returned a null DbConnection.\");\n            connection.ConnectionString = _connectionString;\n            return connection;\n        }\n\n        private static bool IsRunningOnWindows()\n        {\n#if !NETSTANDARD1_3\n            return Environment.OSVersion.Platform == PlatformID.Win32NT;\n#else\n            return System.Runtime.InteropServices.RuntimeInformation.IsOSPlatform(System.Runtime.InteropServices.OSPlatform.Windows);\n#endif\n        }\n\n        private void Initialize()\n        {\n            _escapedSchemaName = _options.SchemaName.Replace(\"]\", \"]]\");\n\n            if (_options.PrepareSchemaIfNecessary)","sourceCodeStart":416,"sourceCodeEnd":452,"githubUrl":"https://github.com/HangfireIO/Hangfire/blob/c236dd0f930f831ec151e436e138ddc429a02a72/src/Hangfire.SqlServer/SqlServerStorage.cs#L416-L452","documentation":"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.","triggerScenarios":"SqlServerStorageOptions.SqlClientFactory is set to a custom or incorrectly configured DbProviderFactory whose CreateCommand/CreateConnection returns null; a corrupted or incompatible SqlClient package installation.","commonSituations":"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.","solutions":["Do not override SqlServerStorageOptions.SqlClientFactory unless necessary; let Hangfire auto-detect based on the referenced package.","If overriding, ensure the factory's CreateConnection returns a non-null DbConnection instance.","Verify that exactly one SqlClient NuGet package (Microsoft.Data.SqlClient or System.Data.SqlClient) is referenced and not corrupted."],"exampleFix":"// before — custom factory returns null\noptions.SqlClientFactory = new MyBrokenFactory();\n// after — use a real factory or remove the override\noptions.SqlClientFactory = Microsoft.Data.SqlClient.SqlClientFactory.Instance;\n// or simply don't set it at all (auto-detection)","handlingStrategy":"validation","validationCode":"var factory = options.SqlClientFactory;\nusing var testConn = factory.CreateConnection()\n    ?? throw new InvalidOperationException(\"Configured SqlClientFactory returns null from CreateConnection.\");\ntestConn.ConnectionString = connectionString;\n// If this succeeds, storage initialization will too.","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Do not override SqlServerStorageOptions.SqlClientFactory unless you have a specific reason.","If overriding, test that CreateConnection returns a non-null instance before configuring storage.","Ensure exactly one SqlClient package is referenced."],"tags":["connection-factory","dbproviderfactory","configuration","sqlclient"],"backgroundTag":null,"analyzedSha":"c236dd0f930f831ec151e436e138ddc429a02a72","analyzedAt":"2026-08-13T20:27:11.027Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}