HangfireIO/Hangfire · error · ArgumentException

The queue name must consist of lowercase letters, digits, un

Error message

The queue name must consist of lowercase letters, digits, underscore, and dash characters only. Given: '{value}'.

What it means

Thrown by EnqueuedState.ValidateQueueName when a queue name contains characters outside the allowed set [a-z0-9_-]. The validation first rejects null/empty/whitespace with ArgumentNullException, then checks each character; any uppercase letter, space, dot, or other symbol trips ArgumentException. This guards the queue identifier that Hangfire persists and routes jobs by.

Source

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

        {
            if (String.IsNullOrWhiteSpace(value))
            {
                throw new ArgumentNullException(nameof(value));
            }

            return ValidateQueueNameInner(value);
        }

        internal static void ValidateQueueName([InvokerParameterName] string parameterName, [NotNull] string value)
        {
            if (String.IsNullOrWhiteSpace(value))
            {
                throw new ArgumentNullException(parameterName);
            }

            if (!ValidateQueueNameInner(value))
            {
                throw new ArgumentException(
                    $"The queue name must consist of lowercase letters, digits, underscore, and dash characters only. Given: '{value}'.",
                    parameterName);
            }
        }

        private static bool ValidateQueueNameInner(string value)
        {
            foreach (var ch in value)
            {
                // ^[a-z0-9_-]+$
                if (!((ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '-' || ch == '_'))
                {
                    return false;
                }
            }

            return true;
        }

View on GitHub (pinned to c236dd0f93)

Solutions

1. Lowercase the queue name and strip/rename any character that is not a-z, 0-9, underscore, or dash before passing it to Hangfire.
2. Check the queues array passed to BackgroundJobServerOptions.Queues / appsettings and normalize all entries at startup.
3. If the name comes from config, add a startup validator that runs ValidateQueueName-style regex ^[a-z0-9_-]+$ and fails fast with a clear message.

Example fix

// before
var queues = new[] { "Default", "high.priority" };

// after
var queues = new[] { "default", "high_priority" };

private static readonly Regex QueueNameRegex = new("^[a-z0-9_-]+$", RegexOptions.Compiled);

static string NormalizeQueueName(string raw)
{
    if (string.IsNullOrWhiteSpace(raw))
        throw new ArgumentException("Queue name is required.", nameof(raw));
    var name = raw.Trim().ToLowerInvariant();
    if (!QueueNameRegex.IsMatch(name))
        throw new ArgumentException(
            $"Queue name '{raw}' must match ^[a-z0-9_-]+$.", nameof(raw));
    return name;
}

static bool IsValidQueueName(string? value) =>
    !string.IsNullOrWhiteSpace(value) &&
    value!.All(c => (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '_' || c == '-');

When it happens

Trigger: Calling any API that sets an EnqueuedState.Queue or passes a queue name string (e.g. BackgroundJob.Enqueue with a queue, UseHangfireServer with a queues array, EnqueuedState constructor) with a value like "MyQueue", "default queue", "q.1", or "Q_DEFAULT".

Common situations: Using CamelCase or PascalCase queue names from app config; reading queue names from an environment variable that contains whitespace; copying a queue name that includes a dot or slash; migrating from another library that allowed uppercase names.

Related errors

• CRON expression is invalid. Please see the inner exception f
• Attempts value must be equal or greater than zero.
• DelaysInSeconds value must be an array of non-negative numbe
• WorkerCount property value should be positive.
• value

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