HangfireIO/Hangfire · error · BackgroundJobClientException

Background job creation failed. See inner exception for deta

Error message

Background job creation failed. See inner exception for details.

What it means

BackgroundJobClient.Create wraps any catchable (non-StackOverflow/non-OutOfMemory style) exception thrown during job creation — opening a storage connection, building the CreateContext, or invoking the IBackgroundJobFactory — into a BackgroundJobClientException with the original error as InnerException. The message is generic because the real cause is in InnerException; always inspect it. This preserves a single exception contract for callers regardless of the underlying storage or serialization failure.

Source

Thrown at src/Hangfire.Core/BackgroundJobClient.cs:163

        /// <inheritdoc />
        public string Create(Job job, IState state, IDictionary<string, object> parameters)
        {
            if (job == null) throw new ArgumentNullException(nameof(job));
            if (state == null) throw new ArgumentNullException(nameof(state));

            try
            {
                using (var connection = _storage.GetConnection())
                {
                    var context = new CreateContext(_storage, connection, job, state, parameters);
                    var backgroundJob = _factory.Create(context);

                    return backgroundJob?.Id;
                }
            }
            catch (Exception ex) when (ex.IsCatchableExceptionType())
            {
                throw new BackgroundJobClientException("Background job creation failed. See inner exception for details.", ex);
            }
        }

        /// <inheritdoc />
        public bool ChangeState(string jobId, IState state, string expectedState)
        {
            if (jobId == null) throw new ArgumentNullException(nameof(jobId));
            if (state == null) throw new ArgumentNullException(nameof(state));

            try
            {
                using (var connection = _storage.GetConnection())
                {
                    var appliedState = _stateChanger.ChangeState(new StateChangeContext(
                        _storage,
                        connection,
                        jobId,
                        state,

View on GitHub (pinned to c236dd0f93)

Solutions

Read the InnerException (and its type) to identify the real failure — connection, serialization, or factory logic.
For storage errors: verify the JobStorage connection string and that the storage backend is reachable.
For serialization errors: ensure job arguments are simple, serializable types; avoid closures and complex object graphs.
Wrap the Create call in try/catch(BackgroundJobClientException) and handle/retry/log appropriately.

Example fix

// before
var id = client.Create(job, state);

// after
try
{
    var id = client.Create(job, state);
}
catch (BackgroundJobClientException ex)
{
    logger.Error(ex.InnerException, "Job creation failed");
    throw;
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check connectivity (best-effort) before creating a job
if (JobStorage.Current == null) throw new InvalidOperationException("JobStorage not configured");

Try / catch

try
{
    var id = client.Create(job, state);
}
catch (BackgroundJobClientException ex)
{
    logger.Error(ex.InnerException, "Job creation failed");
    // retry, queue for later, or surface to caller
}

Prevention

Always inspect InnerException — it carries the real cause.
Ensure job arguments are simple serializable types.
Validate storage connectivity at startup before enqueueing.

When it happens

Trigger: Calling client.Create(job, state) when JobStorage.GetConnection() throws (DB unreachable, Redis down), when the job arguments fail serialization, when a custom IBackgroundJobFactory throws, or when the IState implementation is malformed.

Common situations: Database/Redis connection string wrong or network partition during enqueue; serializing a non-serializable argument (closures, IDisposable); storage schema migration pending; custom factory or state filter that throws.

Related errors

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