RabbitMQ unroutable messages returned: mandatory publishes with no matching binding

Your broker is accepting publishes, no queues are growing, and yet the return_unroutable counter is climbing. Messages are being published with mandatory=true to an exchange that cannot route them to any queue, and RabbitMQ is handing them back to the publisher instead of delivering them.

This is a configuration fault, not an infrastructure fault. The broker is healthy. The routing topology is not. Something changed: a binding was deleted, a queue was removed, an exchange was redeployed without its bindings, or a publisher is using a routing key that matches nothing. Because the publishers set mandatory=true, RabbitMQ is telling you exactly that messages have nowhere to go. The worse case is the default, mandatory=false, where unroutable messages are silently dropped and you see nothing at all.

This guide covers how to confirm the symptom, find which exchange and routing key is broken, and fix it without guesswork.

What this means

When a publisher sends a message with the mandatory flag set, it is making a deal with the broker: if you cannot route this to at least one queue, give it back to me. RabbitMQ honors that with a basic.return frame, which the client library surfaces through a returned-message handler. If the publisher also uses publisher confirms, the basic.return is sent before the basic.ack, because the broker confirms the publish even though the message went nowhere. The confirm tells you the broker accepted the message; it does not tell you the message reached a queue.

The return_unroutable counter in the broker’s message_stats increments every time this happens. Any sustained rate above zero means at least one publisher is emitting messages that match no binding on the target exchange.

flowchart LR
  P[Publisher
mandatory=true] -->|basic.publish| X[Exchange]
  X -->|binding match| Q[Queue]
  X -->|no matching binding| R[basic.return
to publisher]
  R --> C[return_unroutable
counter +1]
  Q --> D[deliver to consumer]

Two interactions change what you observe. First, if an alternate exchange (AE) is configured on the target exchange, unroutable messages are republished to it. That counts as routed for the purposes of the mandatory flag, so no basic.return is sent. Second, if the publisher never registered a return handler in its client library, the broker still sends basic.return and increments the counter, but the application silently swallows the returned message. In both cases the broker-side counter is your ground truth.

Common causes

Quick checks

These are all read-only.

# 1. Confirm the counter and rate, cluster-wide
curl -s -u guest:guest http://localhost:15672/api/overview | jq '.message_stats | {publish, return_unroutable, deliver_get}'

# 2. List bindings on the suspect exchange (replace vhost/exchange; %2f is the default vhost "/")
curl -s -u guest:guest 'http://localhost:15672/api/exchanges/%2f/my.exchange/bindings/source' | jq '.'

# 3. Full binding inventory for the vhost
rabbitmqctl list_bindings source_name source_kind destination_name destination_kind routing_key arguments

# 4. Confirm the queues the publisher expects actually exist
rabbitmqctl list_queues name consumers messages_ready

# 5. Check the exchange's arguments for an alternate exchange
rabbitmqctl list_exchanges name type arguments

If you run the Prometheus plugin, the counter is also exposed as rabbitmq_channel_messages_unroutable_returned_total per channel and rabbitmq_global_messages_unroutable_returned_total as a cluster aggregate. The per-channel metric helps identify which client is affected, but it is not labeled by exchange, so you correlate the channel label back to the connection and application. The companion counter rabbitmq_channel_messages_unroutable_dropped_total tracks the mandatory=false case where messages vanish silently.

How to diagnose it

1. Confirm the rate is real and sustained. Poll /api/overview two or three times a minute apart. return_unroutable is a cumulative counter; compute the rate by differentiation. A one-off burst during a deployment (queues being recreated) is often transient and expected. A sustained rate is a misconfiguration.

2. Identify the affected exchange and vhost. The overview counter is global. Pull per-exchange message_stats to localize: GET /api/exchanges includes message_stats.return_unroutable per exchange. Find the exchange whose counter is incrementing.

3. Dump the exchange’s bindings. Use GET /api/exchanges/{vhost}/{exchange}/bindings/source. If the list is empty, the exchange was declared without bindings, or they were deleted. If the list is non-empty, the problem is a key or pattern mismatch, not a missing binding.

4. Capture a failing routing key. You need one concrete routing key that returned. Options: the publisher’s returned-message handler logs (if it has one), the RabbitMQ firehose tracer (rabbitmqctl trace_on, which adds significant overhead under load, so run it briefly and turn it off), or asking the publishing team which keys they emit. Compare that key against the binding list: exact match for direct exchanges, pattern match for topic exchanges, headers attributes for headers exchanges.

5. Check for an alternate exchange. If the exchange has an alternate-exchange argument, unroutable messages go there instead of being returned. In that case return_unroutable will be zero and the AE’s queues are where your “lost” messages actually are. Inspect the AE’s bindings and depth.

6. Correlate with a change. Returns almost always start at a specific moment: a deployment, a queue cleanup, a Terraform or definitions-file apply. Compare rabbitmqctl list_queues output against your change history for the vhost.

Metrics and signals to monitor

Fixes

Group by what you found in diagnosis.

Missing binding

Re-create the binding with the correct key or pattern: rabbitmqadmin declare binding source=my.exchange destination=my.queue routing_key=order.created.# or via the management UI or definitions file. Then verify with the bindings/source endpoint and watch the return rate drop to zero. If the binding lives in a definitions file or IaC, fix it there too or the next apply will remove it again.

Deleted queue

Redeclare the queue and its bindings, then restart or resubscribe consumers. If the queue was deleted intentionally, the real fix is in the publisher: stop publishing to that route, or point it at the new topology. A correct mandatory publisher logs or retries returned messages; it does not discard them blindly.

Routing key or topic pattern mismatch

Decide which side is wrong. If the publisher’s key is a typo or version skew, fix the publisher. If the binding pattern is too narrow, widen it (for example order.* to order.# on a topic exchange). For topic exchanges, test the failing key against the pattern manually before changing anything: # matches zero or more words, * matches exactly one. A common mistake is expecting wildcard behavior on a direct exchange, where routing keys match exactly and no wildcard matching exists at all.

Alternate exchange gaps

If you added an AE expecting returns and see none, that is the designed behavior: AE routing counts as routed. If you want the safety net and the visibility, consume and monitor the AE’s queues explicitly, or alert on AE queue depth growth.

Plugin-specific behavior

If you use the x-delayed-message exchange plugin, there is a known issue where mandatory=true combined with a non-zero x-delay causes failures. Check the plugin issue tracker before treating returns on a delayed exchange as a topology problem.

Prevention

• Treat bindings as code. Manage exchanges, queues, and bindings through a definitions file or IaC, applied atomically. Ad-hoc UI changes are how bindings silently disappear.
• Publish with mandatory and a return handler. Setting mandatory=true without registering a returned-message handler gets you the broker counter but loses the message and the routing key. The handler should log the exchange, routing key, and message ID at minimum.
• Use publisher confirms with the right mental model. A confirm means “broker accepted it,” not “a queue got it.” Only the return handler (or an AE) protects against unroutable loss.
• Configure an alternate exchange on critical exchanges. It converts silent loss into a visible, consumable backlog. Monitor the AE queue depth.
• Alert on the rate, not the counter. return_unroutable > 0 sustained for 5 minutes is a ticket-worthy condition. It will not escalate to infrastructure damage on its own, so it does not need to page, but every minute it runs, messages are not reaching their destination.
• Cover the silent case. The default mandatory=false drops unroutable messages with no return and no return counter. The complementary detection pattern is “publish rate non-zero, deliver_get zero, queue depth flat.” Monitor that composite, or the Prometheus dropped counter, so the default case is not invisible.

How Netdata helps

• Return unroutable rate as a first-class chart. Netdata collects message_stats from the management API, so return_unroutable is graphed alongside publish, deliver, and ack rates rather than buried in a counter you have to poll by hand.
• Composite pattern detection. The dangerous signature is publish rate non-zero with deliver_get at zero and flat queue depth. Seeing all three on one dashboard is what turns “everything looks green” into “messages are vanishing.”
• Rate computation done for you. Broker counters are cumulative; Netdata differentiates them, so a sustained trickle of returns is visible instead of being lost in a slowly rising total.
• Per-queue context. When you find the broken route, per-queue depth, consumer count, and ack rate confirm whether the destination queue is actually receiving and draining after the fix.
• Topology change correlation. Queue churn (queues created/deleted) on the same timeline as the first returned message usually points straight at the change that broke the binding.

Related guides

• RabbitMQ connection blocked / blocking: publishers frozen by a resource alarm
• RabbitMQ connection in flow state: credit-based backpressure explained
• RabbitMQ consumer timeout: delivery acknowledgement timed out and the channel is closed
• RabbitMQ consumer_utilisation low: consumers attached but not keeping up
• RabbitMQ consumers connected but not acknowledging: the consumer black hole
• RabbitMQ disk free limit alarm: free disk space insufficient and publishing halted
• RabbitMQ disk_free_limit at the default 50MB: the production footgun
• RabbitMQ flow control vs resource alarms: the two throttling mechanisms operators confuse
• RabbitMQ head message age: the queue latency that depth alone cannot show
• How RabbitMQ actually works in production: a mental model for operators
• RabbitMQ memory resource limit alarm: publishers blocked across the whole cluster
• RabbitMQ monitoring checklist: the signals every production broker needs