What causes "Only a single consumer can be connected to a queue: {Name}" in MassTransit/MassTransit?

Give each consumer a unique queue name so each queue has exactly one consumer

MassTransit/MassTransit · error · ConfigurationException

Only a single consumer can be connected to a queue: {Name}

Error message

Only a single consumer can be connected to a queue: {Name}

What it means

MessageQueue.ConnectMessageReceiver attaches a consumer to an in-memory transport queue node. The in-memory fabric models a queue as point-to-point: only one receiver may be bound at a time. When a second consumer (receiver) attempts to connect while one is already registered, the observer/callback connection fails and is rethrown as a ConfigurationException naming the queue — a transport-topology misconfiguration, not a transient fault.

Solutions

Give each consumer a unique queue name so each queue has exactly one consumer
Disconnect the existing receiver (dispose the handle) before connecting a new one
Check endpoint configuration for duplicate queue names

Example fix

// before
// two endpoints both using queue "orders"
// after
cfg.ReceiveEndpoint("orders", e => e.Consumer<OrdersConsumer>());
cfg.ReceiveEndpoint("orders-retry", e => e.Consumer<OrdersRetryConsumer>());

Defensive patterns

Strategy: try-catch

Validate before calling

if (queue.IsConnected)
    throw new InvalidOperationException($"Queue {queue.Name} already has a consumer");

Try / catch

try
{
    handle = queue.ConnectMessageReceiver(receiver);
}
catch (ConfigurationException ex) when (ex.Message.Contains("single consumer"))
{
    // disconnect existing receiver first, then retry
}

Prevention

Use unique queue names per consumer endpoint
Always dispose previous receive handles before reconnecting
Audit receive endpoint configuration for duplicate queue names

When it happens

Trigger: Calling ConnectMessageReceiver on a MessageQueue that already has an active receiver, or when the internal connect callback throws for the queue.

Common situations: Two receive endpoints in bus configuration resolving to the same queue name; restarting a receiver without disconnecting the old handle; accidental duplicate endpoint definitions.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

AI-assisted analysis of MassTransit/MassTransit@62ab339afa (2026-09-13). Data as JSON: /api/errors/a18c242b2f4089a2. Report an issue: GitHub.

Appendix: source

Thrown at src/MassTransit/Transports/Fabric/MessageQueue.cs:57

            _dispatcher = Task.Run(() => StartDispatcher());
        }

        public string Name { get; }

        public TopologyHandle ConnectMessageReceiver(TContext nodeContext, IMessageReceiver<T> receiver)
        {
            try
            {
                var handle = _receivers.Connect(receiver);

                handle = _observer.ConsumerConnected(nodeContext, handle, Name);

                return handle;
            }
            catch (Exception exception)
            {
                throw new ConfigurationException($"Only a single consumer can be connected to a queue: {Name}", exception);
            }
        }

        public async Task Deliver(DeliveryContext<T> context)
        {
            if (context.WasAlreadyDelivered(this))
                return;

            if (context.EnqueueTime.HasValue)
                DeliverWithDelay(context);
            else
            {
                await _channel.Writer.WriteAsync(context, context.CancellationToken).ConfigureAwait(false);

                _metrics.MessageCount.Add();
            }
        }

View on GitHub (pinned to 62ab339afa)