HangfireIO/Hangfire · error · InvalidOperationException

Unknown MSMQ transaction type: + _transactionType

Error message

Unknown MSMQ transaction type:  + _transactionType

What it means

InvalidOperationException thrown at the end of MsmqJobQueue.CreateTransaction's switch when _transactionType is neither MsmqTransactionType.Internal nor MsmqTransactionType.Dtc. Because the enum is extensible/serializable, an unexpected (possibly future or deserialized) value reaches the default branch; the message appends the offending value.

Source

Thrown at src/Hangfire.SqlServer.Msmq/MsmqJobQueue.cs:103

            using (var transaction = new MessageQueueTransaction())
            {
                transaction.Begin();
                messageQueue.Send(message, transaction);
                transaction.Commit();
            }
        }

        private IMsmqTransaction CreateTransaction()
        {
            switch (_transactionType)
            {
                case MsmqTransactionType.Internal:
                    return new MsmqInternalTransaction();
                case MsmqTransactionType.Dtc:
                    return new MsmqDtcTransaction();
            }

            throw new InvalidOperationException("Unknown MSMQ transaction type: " + _transactionType);
        }

        private MessageQueue GetMessageQueue(string queue)
        {
            return new MessageQueue(String.Format(CultureInfo.InvariantCulture, _pathPattern, queue));
        }
    }
}

View on GitHub (pinned to c236dd0f93)

Solutions

1. Set the MSMQ transaction type to one of the supported values: MsmqTransactionType.Internal or MsmqTransactionType.Dtc.
2. Ensure the Hangfire.SqlServer.Msmq package version matches (or is newer than) the code that supplies the enum value.
3. Validate the configured value against the known set at startup and fail with a clearer message.

Example fix

// before
.UseMsmqQueues(path, MsmqTransactionType.None) // unsupported value

// after
.UseMsmqQueues(path, MsmqTransactionType.Internal)

static readonly HashSet<MsmqTransactionType> Supported =
    new() { MsmqTransactionType.Internal, MsmqTransactionType.Dtc };

static MsmqTransactionType AssertSupported(MsmqTransactionType type)
{
    if (!Supported.Contains(type))
        throw new ArgumentOutOfRangeException(nameof(type), type, "Unsupported MSMQ transaction type.");
    return type;
}

When it happens

Trigger: Constructing MsmqJobQueue (via UseMsmqQueues configuration) with an MsmqTransactionType value outside the two supported cases; deserializing a config that introduced a new enum member not handled by this version.

Common situations: Upgrading Hangfire.SqlServer.Msmq to a version that adds a new transaction type while the calling code passes it to an older library; manually casting an int to MsmqTransactionType; misconfiguration of the MSMQ transaction option in code/config.

Related errors

• Unable to parse queue path '{queuePath}'
• 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/4dc07a15478fbfac. Report an issue: GitHub.