HangfireIO/Hangfire · error · ArgumentNullException

connection

Error message

connection

What it means

The SqlServerObjectsInstaller.Install method received a null connection argument. This is a standard ArgumentNullException guard at the top of the Install(DbConnection, string, bool) overload that executes the schema installation SQL script.

Source

Thrown at src/Hangfire.SqlServer/SqlServerObjectsInstaller.cs:44

    {
        [Obsolete("This field is unused and will be removed in 2.0.0.")]
        public static readonly int RequiredSchemaVersion = 5;

        public static readonly int LatestSchemaVersion = 9;

        public static void Install(DbConnection connection)
        {
            Install(connection, null);
        }

        public static void Install(DbConnection connection, string schema)
        {
            Install(connection, schema, false);
        }

        public static void Install(DbConnection connection, string schema, bool enableHeavyMigrations)
        {
            if (connection == null) throw new ArgumentNullException(nameof(connection));

            var script = GetInstallScript(schema, enableHeavyMigrations);

            connection.Execute(script, commandTimeout: 0);
        }

        public static string GetInstallScript(string schema, bool enableHeavyMigrations)
        {
            var script = GetStringResource(
                typeof(SqlServerObjectsInstaller).GetTypeInfo().Assembly,
                "Hangfire.SqlServer.Install.sql");

            script = script.Replace("$(HangFireSchema)", !string.IsNullOrWhiteSpace(schema) ? schema : Constants.DefaultSchema);

            if (!enableHeavyMigrations)
            {
                script = script.Replace("--SET @DISABLE_HEAVY_MIGRATIONS = 1;", "SET @DISABLE_HEAVY_MIGRATIONS = 1;");
            }

View on GitHub (pinned to c236dd0f93)

Solutions

1. Ensure a valid, open DbConnection is passed to Install.
2. Create and open the connection before calling Install, disposing it afterward.
3. Add a null check with a meaningful message before calling Install.

Example fix

// before
SqlServerObjectsInstaller.Install(maybeNullConnection, "Hangfire");
// after
using var conn = new SqlConnection(connectionString);
conn.Open();
SqlServerObjectsInstaller.Install(conn, "Hangfire");

DbConnection connection = /* creation */;
if (connection == null)
    throw new InvalidOperationException("Cannot install schema: connection is null.");
if (connection.State != ConnectionState.Open)
    connection.Open();

SqlServerObjectsInstaller.Install(connection, schema);

static bool IsInstallableConnection(DbConnection conn) => conn != null && conn.State == ConnectionState.Open;

When it happens

Trigger: Calling SqlServerObjectsInstaller.Install(null, schema); a connection that failed to open or was never created being passed to schema installation.

Common situations: Custom initialization code that creates a connection conditionally and passes null on the failure path; DI misconfiguration; testing helpers that skip connection creation.

Related errors

• existingConnection
• nameOrConnectionString
• connectionFactory
• featureId
• Attempts value must be equal or greater than zero.

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