NO_ROUTE (312): unroutable RabbitMQ messages and the mandatory flag

2026-10-19 · 2 min read · Viktor Baumann

basic.return: 312 NO_ROUTE

You see this in a client's return callback, not as an error that closes anything. It means the exchange had no binding that matched the message's routing key. Measured on RabbitMQ 4.3.6:

Publish with a routing key no binding matches	Result
`mandatory=True`	the message comes back with `312 NO_ROUTE`
without `mandatory`	dropped, no return, no error
with publisher confirms, without `mandatory`	confirmed, and dropped

So an unroutable message is only reported when you ask for it. Without mandatory, a typo in a routing key, a binding removed in a deploy or a consumer service that has not started yet loses messages silently.

Handling the return

Publish with mandatory=True and register a return callback (pika: channel.add_on_return_callback; Java: channel.addReturnListener; Spring: RabbitTemplate.setReturnsCallback with mandatory set).
With publisher confirms, a returned message is still confirmed afterwards. The return is the signal; the confirm alone tells you nothing about routing. pika's BlockingChannel with confirm_delivery() raises UnroutableError for you.
Decide what a return means: retry later, park the message, or alert. Logging and dropping it is a decision too, but it should be one.

Catching unroutable messages in the broker

An alternate exchange on the exchange receives every message it cannot route, without any client change:

rabbitmqctl set_policy orders-ae '^orders$' '{"alternate-exchange":"orders.unrouted"}' --apply-to exchanges

Bind a queue to orders.unrouted and unroutable messages wait there instead of disappearing. The same works for a dead-letter exchange, where a dead letter with no matching binding is otherwise dropped too.