How does the mandatory flag together with ReturnsCallback handle unroutable messages, and why can't publisher confirms alone detect them?

## Why confirms miss unroutable messages When you publish to an exchange, the exchange applies its binding rules. If **no bound queue matches** the routing key, the default AMQP behaviour is to **silently drop** the message. Critically, the broker still considers it 'handled' and sends a **publisher confirm ack** — because from the broker's perspective it accepted and processed the publish. So publisher confirms report success even though the message vanished. This is the exact blind spot the mandatory flag fills. ## The mandatory flag The AMQP `mandatory` flag tells the broker: *if this message cannot be routed to at least one queue, do not drop it — return it to me.* In Spring AMQP: ```java rabbitTemplate.setMandatory(true); ``` and you must enable returns on the connection factory: ```java cachingConnectionFactory.setPublisherReturns(true); ``` (Setting `ConfirmType.CORRELATED`/`SIMPLE` handles confirms; `setPublisherReturns(true)` handles returns — they're independent switches.) ## ReturnsCallback Register a **`RabbitTemplate.ReturnsCallback`** (the modern functional interface; the older `ReturnCallback` took separate params): ```java rabbitTemplate.setReturnsCallback(returned -> { log.warn("Unroutable: exchange={} rk={} code={} text={} body={}", returned.getExchange(), returned.getRoutingKey(), returned.getReplyCode(), returned.getReplyText(), new String(returned.getMessage().getBody())); }); ``` The callback receives a single **`ReturnedMessage`** object bundling: the `Message`, the `replyCode` (e.g. 312 NO_ROUTE), the `replyText`, the `exchange`, and the `routingKey`. This tells you exactly which message failed to route and why. ## Ordering and interaction with confirms — the key gotcha For an unroutable mandatory message the sequence is: 1. **Return** is delivered first — `ReturnsCallback` fires. 2. **Confirm** is delivered after — and it is an **ack** (`ack=true`), not a nack. So an unroutable message produces BOTH a return AND a positive confirm. A naive producer that only watches confirms will think everything is fine. Reliable code interprets: - **nack (ack=false)** = broker did not accept the message at all. - **return** = broker accepted it but couldn't route it to any queue. - **ack + no return** = accepted and routed (the happy path). ## alternate-exchange as an alternative Instead of returns you can bind an **alternate-exchange** to the primary exchange (`x-alternate-exchange` argument) so unroutable messages flow to a catch-all exchange/queue rather than being returned. Returns and alternate-exchange solve the same problem differently; pick one. ## Gotchas - Forgetting `setPublisherReturns(true)` on the factory means the `ReturnsCallback` never fires even with `setMandatory(true)`. - The callback runs on an amqp/listener thread — keep it fast. - Returns catch 'no queue matched'; they do NOT catch 'queue exists but is full/rejecting' — those are different. - Mandatory does not wait; it's still asynchronous like confirms. ## When to use Use mandatory + returns whenever a misconfigured binding or a typo'd routing key must not silently swallow messages — pair it with confirms so you cover both 'not accepted' and 'accepted but unroutable'.