Dead letter exchanges and queues in RabbitMQ - Commands & Configuration

Introduction

Sometimes messages in a queue cannot be processed. Dead letter exchanges and queues help catch these messages so they are not lost and can be inspected or retried later.

When a message is rejected or expired and you want to keep it for later analysis.

When your application cannot process certain messages and you want to separate them from normal traffic.

When you want to track messages that failed to be delivered after several attempts.

When you want to avoid losing messages that cause errors in your system.

When you want to debug why some messages are not processed correctly.

Config File - dead_letter_setup.sh

dead_letter_setup.sh

#!/bin/bash

# Create the dead letter exchange
rabbitmqadmin declare exchange name=dlx type=direct

# Create the dead letter queue
rabbitmqadmin declare queue name=dead_letter_queue durable=true

# Bind the dead letter queue to the dead letter exchange
rabbitmqadmin declare binding source=dlx destination=dead_letter_queue routing_key=dead_letter_key

# Create the main exchange
rabbitmqadmin declare exchange name=main_exchange type=direct

# Create the main queue with dead letter exchange settings
rabbitmqadmin declare queue name=main_queue durable=true arguments='{"x-dead-letter-exchange":"dlx", "x-dead-letter-routing-key":"dead_letter_key"}'

# Bind the main queue to the main exchange
rabbitmqadmin declare binding source=main_exchange destination=main_queue routing_key=main_key

This script sets up RabbitMQ with a dead letter exchange (dlx) and a dead letter queue (dead_letter_queue). The main queue (main_queue) is configured to send messages to the dead letter exchange if they are rejected or expire. The dead letter exchange routes these messages to the dead letter queue using the routing key 'dead_letter_key'.

Commands

Create a direct exchange named 'dlx' to handle dead letter messages.

Terminal

rabbitmqadmin declare exchange name=dlx type=direct

Expected Output

Exchange 'dlx' declared successfully.

Create a durable queue named 'dead_letter_queue' to store dead letter messages.

Terminal

rabbitmqadmin declare queue name=dead_letter_queue durable=true

Expected Output

Queue 'dead_letter_queue' declared successfully.

Bind the dead letter queue to the dead letter exchange with routing key 'dead_letter_key'.

Terminal

rabbitmqadmin declare binding source=dlx destination=dead_letter_queue routing_key=dead_letter_key

Expected Output

Binding from exchange 'dlx' to queue 'dead_letter_queue' with routing key 'dead_letter_key' declared successfully.

Create the main exchange named 'main_exchange' where normal messages are sent.

Terminal

rabbitmqadmin declare exchange name=main_exchange type=direct

Expected Output

Exchange 'main_exchange' declared successfully.

Create the main queue named 'main_queue' with dead letter exchange settings so rejected or expired messages go to 'dlx'.

Terminal

rabbitmqadmin declare queue name=main_queue durable=true arguments='{"x-dead-letter-exchange":"dlx", "x-dead-letter-routing-key":"dead_letter_key"}'

Expected Output

Queue 'main_queue' declared successfully.

→

arguments - Set dead letter exchange and routing key for the queue

Bind the main queue to the main exchange with routing key 'main_key'.

Terminal

rabbitmqadmin declare binding source=main_exchange destination=main_queue routing_key=main_key

Expected Output

Binding from exchange 'main_exchange' to queue 'main_queue' with routing key 'main_key' declared successfully.

Key Concept

If a message cannot be processed, it is sent to a special dead letter queue via a dead letter exchange for later inspection or retry.

Common Mistakes

Not setting the 'x-dead-letter-exchange' argument on the main queue.

Messages that fail will be lost because they have nowhere to go.

Always configure the main queue with 'x-dead-letter-exchange' and optionally 'x-dead-letter-routing-key'.

Forgetting to bind the dead letter queue to the dead letter exchange.

Dead letter messages will not be routed to any queue and will be lost.

Bind the dead letter queue to the dead letter exchange with the correct routing key.

Using the wrong routing key in the dead letter queue binding.

Messages sent to the dead letter exchange will not reach the dead letter queue.

Ensure the routing key in the queue binding matches the 'x-dead-letter-routing-key' set on the main queue.

Summary

Create a dead letter exchange and a dead letter queue to catch failed messages.

Configure the main queue with 'x-dead-letter-exchange' and 'x-dead-letter-routing-key' to redirect failed messages.

Bind queues to exchanges with matching routing keys to ensure proper message routing.