Dead Letter Exchanges

The x-dead-letter-exchange argument to queue.declare controls the exchange to which messages from that queue are 'dead-lettered'. A message is dead-lettered when any of the following events occur:

Using Dead Letter Exchanges

Dead letter exchanges are normal exchanges. They can be any of the usual types and are declared as usual.

To set the dead letter exchange for a queue, set the x-dead-letter-exchange argument to the name of the exchange:

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

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

The code above declares a new exchange called some.exchange.name and sets this new exchange as the dead letter exchange for a newly created queue. Note that the exchange does not have to be declared when the queue is declared, but it should exist by the time messages need to be dead-lettered; if it is missing then, the messages will be silently dropped.

You may also specify a routing key to be used when dead-lettering messages. If this is not set, the message's own routing keys will be used.

args.put("x-dead-letter-routing-key", "some-routing-key");

Routing Dead-Lettered Messages

Dead-lettered messages are routed to their dead letter exchange either:

For example, if you publish a message to an exchange with routing key foo, and that message is dead-lettered, it will be published to its dead letter exchange with routing key foo. If the queue the message originally landed on had been declared with x-dead-letter-routing-key set to bar, then the message will be published to its dead letter exchange with routing key bar.

Note that, if a specific routing key was not set for the queue, messages on it are dead-lettered with all their original routing keys. This includes routing keys added by the CC and BCC headers (see Sender-selected distribution for details on these two headers).

Dead-lettered messages are re-published with publisher confirms turned on internally so, the dead-letter queues the messages eventually land on must confirm the messages before they are removed from the original queue. In other words, the publishing queue will not remove messages before the dead-letter queues acknowledge receiving them (see Confirms for details on the guarantees made). Note that, in the event of an unclean broker shutdown, the same message may be duplicated on both the original queue and on the dead-letter queues.

It is possible to form a cycle of dead-letter queues. For instance, this can happen when a queue dead-letters messages to the default exchange without specifiying a dead-letter routing key. Messages in such cycles (i.e. messages that reach the same queue twice) will be dropped.

Dead-Lettered Messages

Dead-lettering a message modifies its headers:

The dead-lettering process adds an array to the header of each dead-lettered message named x-death. This array contains an entry for each time the message was dead-lettered. Each such entry is a table that consists of several fields:

The reason is a name describing why the message was dead-lettered and is one of the following:

Note that the array is sorted most-recent-first, so the most recent dead-lettering will be recorded in the first entry.