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 the EnqueuedState.Handler.Apply when the background job's method carries a Queue (e.g. via [Queue("...")] on the method or Job.Queue set) but the configured JobStorage does not advertise the JobQueueFeatures.JobQueueProperty capability. Hangfire only honors a per-job queue override on storages that explicitly support it; otherwise you must select the queue at the server level.

Source

Thrown at src/Hangfire.Core/States/EnqueuedState.cs:278

            }

            return true;
        }

        internal sealed class Handler : IStateHandler
        {
            public void Apply(ApplyStateContext context, IWriteOnlyTransaction transaction)
            {
                var enqueuedState = context.NewState as EnqueuedState;
                if (enqueuedState == null)
                {
                    throw new InvalidOperationException(
                        $"`{typeof (Handler).FullName}` state handler can be registered only for the Enqueued state.");
                }

                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.");
                }

                transaction.AddToQueue(
                    context.BackgroundJob.Job?.Queue == null || !DefaultQueue.Equals(enqueuedState.Queue, StringComparison.OrdinalIgnoreCase)
                        ? enqueuedState.Queue
                        : context.BackgroundJob.Job.Queue,
                    context.BackgroundJob.Id);
            }

            public void Unapply(ApplyStateContext context, IWriteOnlyTransaction transaction)
            {
            }

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

View on GitHub (pinned to c236dd0f93)

Solutions

Remove the [Queue] attribute from the job method and route the job through a server that listens on the desired queue via BackgroundJobServerOptions.Queues.
If per-job queuing is required, switch to or extend a storage that sets JobStorageFeatures.JobQueueProperty in its features.
Check storage.Features at startup and log a warning when the app uses [Queue] but the feature is absent.

Example fix

// before
[Queue("critical")]
public void SendEmail(string to) { ... }

// after (route via server queues instead)
public void SendEmail(string to) { ... }
// server: new BackgroundJobServer(new BackgroundJobServerOptions { Queues = new[] { "critical", "default" } });

Defensive patterns

Strategy: validation

Validate before calling

static bool StorageSupportsJobQueue(JobStorage storage)
    => storage.HasFeature(JobStorageFeatures.JobQueueProperty);

// at startup:
if (JobStorage.Current != null && !StorageSupportsJobQueue(JobStorage.Current))
    Console.WriteLine("Warning: current storage does not support per-job [Queue]; remove the attribute.");

Try / catch

try
{
    client.Create(job, initialState);
}
catch (NotSupportedException ex) when (ex.Message.Contains("QueueAttribute"))
{
    // fall back: enqueue without per-job queue, let server queues handle routing
    client.Create(job with { Queue = null }, initialState);
}

Prevention

Decide queue selection strategy up front: per-job [Queue] requires a capable storage.
Write an integration test that asserts your storage advertises JobQueueProperty when you rely on [Queue].
Document, per environment, whether [Queue] is allowed.

When it happens

Trigger: Decorating a job method with [Queue("custom")] or constructing a Job with a non-null Queue while using a storage whose JobStorageFeatures does not include JobQueueProperty (e.g. some custom or in-memory storage implementations).

Common situations: Switching from SqlServer/Redis storage (which support the feature) to a minimal custom storage; writing a test storage that did not opt into the JobQueueProperty feature flag; applying [Queue] attribute assuming all storages honor it.

Related errors

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