{"record":{"id":"c9585cd51371e37e","repo":"HangfireIO/Hangfire","slug":"the-queue-name-must-consist-of-lowercase-letters","errorCode":null,"errorMessage":"The queue name must consist of lowercase letters, digits, underscore, and dash characters only. Given: '{value}'.","messagePattern":"The queue name must consist of lowercase letters, digits, underscore, and dash characters only\\. Given: '(.+?)'\\.","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/Hangfire.Core/States/EnqueuedState.cs","lineNumber":245,"sourceCode":"        {\n            if (String.IsNullOrWhiteSpace(value))\n            {\n                throw new ArgumentNullException(nameof(value));\n            }\n\n            return ValidateQueueNameInner(value);\n        }\n\n        internal static void ValidateQueueName([InvokerParameterName] string parameterName, [NotNull] string value)\n        {\n            if (String.IsNullOrWhiteSpace(value))\n            {\n                throw new ArgumentNullException(parameterName);\n            }\n\n            if (!ValidateQueueNameInner(value))\n            {\n                throw new ArgumentException(\n                    $\"The queue name must consist of lowercase letters, digits, underscore, and dash characters only. Given: '{value}'.\",\n                    parameterName);\n            }\n        }\n\n        private static bool ValidateQueueNameInner(string value)\n        {\n            foreach (var ch in value)\n            {\n                // ^[a-z0-9_-]+$\n                if (!((ch >= 'a' && ch <= 'z') || (ch >= '0' && ch <= '9') || ch == '-' || ch == '_'))\n                {\n                    return false;\n                }\n            }\n\n            return true;\n        }","sourceCodeStart":227,"sourceCodeEnd":263,"githubUrl":"https://github.com/HangfireIO/Hangfire/blob/c236dd0f930f831ec151e436e138ddc429a02a72/src/Hangfire.Core/States/EnqueuedState.cs#L227-L263","documentation":"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.","triggerScenarios":"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\".","commonSituations":"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.","solutions":["Lowercase the queue name and strip/rename any character that is not a-z, 0-9, underscore, or dash before passing it to Hangfire.","Check the queues array passed to BackgroundJobServerOptions.Queues / appsettings and normalize all entries at startup.","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."],"exampleFix":"// before\nvar queues = new[] { \"Default\", \"high.priority\" };\n\n// after\nvar queues = new[] { \"default\", \"high_priority\" };","handlingStrategy":"validation","validationCode":"private static readonly Regex QueueNameRegex = new(\"^[a-z0-9_-]+$\", RegexOptions.Compiled);\n\nstatic string NormalizeQueueName(string raw)\n{\n    if (string.IsNullOrWhiteSpace(raw))\n        throw new ArgumentException(\"Queue name is required.\", nameof(raw));\n    var name = raw.Trim().ToLowerInvariant();\n    if (!QueueNameRegex.IsMatch(name))\n        throw new ArgumentException(\n            $\"Queue name '{raw}' must match ^[a-z0-9_-]+$.\", nameof(raw));\n    return name;\n}","typeGuard":"static bool IsValidQueueName(string? value) =>\n    !string.IsNullOrWhiteSpace(value) &&\n    value!.All(c => (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '_' || c == '-');","tryCatchPattern":null,"preventionTips":["Centralize queue-name normalization in one helper used by both enqueue and server-setup code.","Validate the queues array from configuration at startup and fail fast.","Add a unit test asserting each configured queue matches ^[a-z0-9_-]+$."],"tags":["validation","queue-naming","argument"],"backgroundTag":null,"analyzedSha":"c236dd0f930f831ec151e436e138ddc429a02a72","analyzedAt":"2026-08-13T20:27:11.027Z","schemaVersion":2},"datasetVersion":"2026-08-14T00:17:13.853Z"}