Properly setting up dead-letter queues in RabbitMQ

Creating a dead-letter exchange

the first thing we need to do is to create a dead-letter exchange. This exchange will be used to route messages that are rejected by our application. Open RabbitGUI and go to the "Exchanges" menu and click on "New". Give it a name, for example events.dead-letter, and select the type fanout. This means that all messages sent to this exchange will be routed to all queues bound to it.

Creating a policy to automatically re-route rejected messages

To avoid manually specifying the dead-letter exchange for each queue, we can create a policy that will automatically re-route rejected messages to our dead-letter exchange. Create a policy that is applied to all queues, and set the "Dead-letter exchange" to the one we just created (events.dead-letter). This way, all messages that are rejected by our application will be automatically routed to the dead-letter exchange.

To check that the policy is correctly applied, go to any queue in the settings tab and check that the policy is applied and the dead-letter exchange is set properly.

To learn more about debugging policies in RabbitMQ, read our article on debugging RabbitMQ policies.

Creating a dead-letter queue

We need to create a queue that will receive the messages that are rejected by our application. To do that, go to the "Queues" menu and click on "New". Give it a name, for example dlq.catch-all, and keep everything else empty.

This queue will have no consumer, it is only meant to store messages that are rejected. It is your job to later inspect this queue and decide what to do with the messages. You can re-publish them, delete them, or let them eventually die.

Routing all rejected messages to the dead-letter queue

Now that all rejected messages are routed to the dead letter exchange, we need to bind the exchange to our queue. To do that go to the "Routing" tab of your queue and add a binding to the dead-letter exchange:

Since we created a fanout exchange, all messages will be routed to our queue regardless of their routing key. This is why RabbitGUI does not ask for a routing key when binding the exchange to the queue. This will have the benefit of preserving the existing message's routing key, which is useful if you want to re-publish them later.

Re-publishing messages from the dead-letter queue

RabbitGUI lets you easily manage dead-letter queues. You can filter messages, re-publish them, and even throttle the re-publishing process to avoid overwhelming your RabbitMQ server. Read more in our dedicated article on introspecting dead-letter queues with RabbitMQ.