HangfireIO/Hangfire · error · InvalidOperationException

Unable to parse queue path '{queuePath}'

Error message

Unable to parse queue path '{queuePath}'

What it means

InvalidOperationException thrown by MessageQueueExtensions.GetQueuePathMatch when a regex applied to an MSMQ queue path does not produce exactly one match. Hangfire.SqlServer.Msmq expects a well-formed MSMQ queue path (e.g. FormatName:DIRECT=OS:machine\private$\queue or machine\queue) to parse into computer/queue parts; zero or multiple matches mean the string is not a recognizable MSMQ path.

Source

Thrown at src/Hangfire.SqlServer.Msmq/MessageQueueExtensions.cs:108

        {
            var match = GetQueuePathMatch(messageQueue.Path);

            var computerName = match.Groups["computerName"].Value;
            var queueType = match.Groups["queueType"].Value;
            var queue = match.Groups["queue"].Value;

            if (computerName == ".")
                computerName = null;

            return GetQueueCount(computerName, queueType, queue);
        }

        internal static Match GetQueuePathMatch(string queuePath)
        {
            var matches = regex.Matches(queuePath);
            if (matches.Count != 1)
            {
                throw new InvalidOperationException($"Unable to parse queue path '{queuePath}'");
            }

            return matches[0];
        }

        private static long GetQueueCount(string computerName, string queueType, string queue)
        {
            if (string.IsNullOrEmpty(computerName)) computerName = null;
            string queuePath = $"queue=Direct=OS:{computerName ?? "."}";

            if (!String.IsNullOrEmpty(queueType))
            {
                queuePath += $"\\{queueType}";
            }

            queuePath += $"\\{queue}";

            return GetCount(computerName, queuePath);

View on GitHub (pinned to c236dd0f93)

Solutions

1. Correct the path to the standard MSMQ format, e.g. @".\private$\hangfire" or "FormatName:DIRECT=OS:machine\\private$\queue".
2. Verify the queue exists in the MSMQ snap-in / Computer Management before referencing it.
3. Normalize all configured queue paths through a single helper that validates the regex up front.

Example fix

// before
GlobalConfiguration.Configuration.UseSqlServerStorage(cs).UseMsmqQueues(@"bad:path\\MyQueue");

// after
GlobalConfiguration.Configuration.UseSqlServerStorage(cs).UseMsmqQueues(@".\private$\hangfire");

static readonly Regex MsmqPath =
    new(@"^(?:FormatName:Direct=OS:)?(?<computer>[^\\]+)\\(?:private\\$\\)?(?<queue>[^\\]+)$",
        RegexOptions.Compiled | RegexOptions.IgnoreCase);

static string AssertValidMsmqPath(string path)
{
    if (!MsmqPath.IsMatch(path))
        throw new ArgumentException($"Invalid MSMQ queue path: '{path}'.");
    return path;
}

When it happens

Trigger: Configuring SqlServerStorage with MSMQ dequeuing (UseMsmqQueues) and passing a queue path string that does not match the expected MSMQ path grammar; counting queues on a malformed path.

Common situations: Typing the queue path with wrong separators; using a label or description instead of a FormatName/path; missing the private$ segment; copy-paste introducing extra characters; environment-specific path differences.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Unknown MSMQ transaction type: + _transactionType
• Attempts value must be equal or greater than zero.
• DelaysInSeconds value must be an array of non-negative numbe
• client
• storage

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