Help Center/ Distributed Message Service for RabbitMQ/ User Guide/ Managing Messages/ Configuring RabbitMQ Dead Letter Messages
Updated on 2026-07-14 GMT+08:00
View PDF

Configuring RabbitMQ Dead Letter Messages

Dead lettering is a message mechanism in RabbitMQ. When a message is consumed, it becomes a dead letter message if any of the following happens:

  • requeue is set to false, and the consumer uses basic.reject or basic.nack to negatively acknowledge (NACK) the message.
  • The message has stayed in the queue for a time longer than the configured TTL.
  • The number of messages in the queue exceeds the maximum queue length.

Such a message will be stored in a dead letter queue, if any, for special treatment. If there is no dead letter queue, the message will be discarded.

For more information about dead lettering, see Dead Letter Exchanges.

Notes and Constraints

RabbitMQ dead letter messages may affect performance. Exercise caution.

Dead Letter Message Routing Process

  1. A producer sends a message to an exchange.
  2. The exchange routes the message to a queue.
  3. A consumer pulls the message from the queue.
  4. Check whether the message expires, whether the number of messages reaches the upper limit, or consumer makes a negative acknowledgment. If yes, the message becomes a dead letter message.
  5. The queue sends the dead letter message to the dead letter exchange based on x-dead-letter-exchange and sets the dead letter routing key for the dead letter message based on x-dead-letter-routing-key.
  6. The dead letter exchange routes the dead letter message to the dead letter queue.

Configuring an Exchange Key and a Routing Key on a Java Client

To configure a dead letter exchange for a queue, specify the x-dead-letter-exchange and x-dead-letter-routing-key parameters when creating the queue. The queue sends the dead letter message to the dead letter exchange based on x-dead-letter-exchange and sets the dead letter routing key for the dead letter message based on x-dead-letter-routing-key.

The following example shows how to configure a dead letter exchange and routing information on a Java client.

channel.exchangeDeclare("some.exchange.name", "direct");

Map<String, Object> args = new HashMap<String, Object>();
args.put("x-dead-letter-exchange", "some.exchange.name");
args.put("x-dead-letter-routing-key", "some-routing-key");
channel.queueDeclare("myqueue", false, false, false, args);

Configuring a Dead Letter Exchange and Routing Key on the RabbitMQ Console

  1. Create a queue by referring to Creating a RabbitMQ Queue, select the dead letter exchange in Dead Letter Exchange, and enter the dead letter routing key in Dead Letter Routing Key.

    Figure 1 Configuring a dead letter exchange and routing key

  2. In the queue list, click View Detail next to the created queue.

    If the dead letter exchange and routing key are the same as those set in 1, the dead letter exchange and routing key are configured successfully.

    Figure 2 Viewing the dead letter exchange and routing key

Parent topic: Managing Messages