Updated on 2025-07-14 GMT+08:00

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 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.

RabbitMQ dead letter messages may compromise performance. Exercise caution.

Configuring a Dead Letter Exchange and Routing Key

A dead letter exchange and routing key can be configured on a client or on the RabbitMQ console.

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);
  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 queue details