HangfireIO/Hangfire · error · NotSupportedException

Current storage doesn't support specifying queues directly f

Error message

Current storage doesn't support specifying queues directly for a specific job. Please use the QueueAttribute instead.

What it means

Thrown by ScheduledState.Handler's CheckJobQueueFeatureIsSupported, identical in spirit to error 201 but for the Scheduled state path. It fires when a scheduled job method has a Queue value (e.g. [Queue]) yet the active JobStorage does not declare JobStorageFeatures.JobQueueProperty. Per-job queue selection is only honored by storages that opt in.

Source

Thrown at src/Hangfire.Core/States/ScheduledState.cs:203

            public void Unapply(ApplyStateContext context, IWriteOnlyTransaction transaction)
            {
                CheckJobQueueFeatureIsSupported(context);

                transaction.RemoveFromSet(
                    "schedule",
                    context.BackgroundJob.Job?.Queue == null
                        ? context.BackgroundJob.Id
                        : context.BackgroundJob.Job.Queue + ':' + context.BackgroundJob.Id);
            }

            // ReSharper disable once MemberHidesStaticFromOuterClass
            public string StateName => ScheduledState.StateName;

            private static void CheckJobQueueFeatureIsSupported(ApplyStateContext context)
            {
                if (context.BackgroundJob.Job?.Queue != null && !context.Storage.HasFeature(JobStorageFeatures.JobQueueProperty))
                {
                    throw new NotSupportedException("Current storage doesn't support specifying queues directly for a specific job. Please use the QueueAttribute instead.");
                }
            }
        }
    }
}

View on GitHub (pinned to c236dd0f93)

Solutions

Remove the [Queue] attribute and have the worker server subscribe to the queue via BackgroundJobServerOptions.Queues.
Use a storage that enables JobStorageFeatures.JobQueueProperty, or extend your custom storage to advertise it.
At startup, detect [Queue] usage against storage.Features and fail or warn early.

Example fix

// before
[Queue("bulk")]
public void RunReport() { ... }
BackgroundJob.Schedule(() => RunReport(), TimeSpan.FromHours(1));

// after
public void RunReport() { ... }
BackgroundJob.Schedule(() => RunReport(), TimeSpan.FromHours(1));
// worker: Queues = new[] { "bulk", "default" }

Defensive patterns

Strategy: validation

Validate before calling

if (JobStorage.Current != null && !JobStorage.Current.HasFeature(JobStorageFeatures.JobQueueProperty))
    throw new InvalidOperationException(
        "Current storage cannot honor [Queue]; remove the attribute or change storage.");

Try / catch

try { BackgroundJob.Schedule(() => Work(), delay); }
catch (NotSupportedException ex) when (ex.Message.Contains("QueueAttribute"))
{
    // remove per-job queue and rely on server queues
}

Prevention

Keep [Queue] usage gated on a storage-capability check at startup.
Prefer server-side Queues configuration over per-method [Queue] when storage support is uncertain.
Add an integration test that schedules with [Queue] and asserts no NotSupportedException.

When it happens

Trigger: Scheduling a job (BackgroundJob.Schedule) whose method carries [Queue("...")] or a manually-set Job.Queue, while using a storage without the JobQueueProperty feature.

Common situations: Adding [Queue] to a method assuming all storages honor it; testing against a lightweight/custom storage that omits the feature flag; mixing storages across environments.

Related errors

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