Dead Letter Exchanges

Overview

Messages from a queue can be "dead-lettered"; that is, republished to an exchange when any of the following events occur:

• The message is negatively acknowledged by a consumer using basic.reject or basic.nack with requeue parameter set to false.
• The message expires due to per-message TTL; or
• The message is dropped because its queue exceeded a length limit

Note that expiration of a queue will not dead letter the messages in it.

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

For any given queue, a DLX can be defined by clients using the queue's arguments, or in the server using policies. In the case where both policy and arguments specify a DLX, the one specified in arguments overrules the one specified in policy.

Configuration using policies is recommended as it allows for DLX reconfiguration that does not involve application redeployment.

Configuration Using a Policy

To specify a DLX using policy, add the key "dead-letter-exchange" to a policy definition. For example:

rabbitmqctl	rabbitmqctl set_policy DLX ".*" '{"dead-letter-exchange":"my-dlx"}' --apply-to queues
rabbitmqctl (Windows)	rabbitmqctl set_policy DLX ".*" "{""dead-letter-exchange"":""my-dlx""}" --apply-to queues

The policy above applies the DLX "my-dlx" to all queues. This is merely an example, in practice different sets of queues will likely use different dead lettering settings (or none at all)

Similarly, an explicit routing key can be specified by adding the key "dead-letter-routing-key" to the policy.

Policies can also be defined using the management plugin, see the policy documentation for more details.

Configuration Using Optional Queue Arguments

To set the dead letter exchange for a queue, specify the optional x-dead-letter-exchange argument when declaring the queue. The value must be an exchange name in the same virtual host:

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");

When a dead letter exchange has been specified, in addition to the usual configure permissions on the declared queue, the user needs to have read permissions on that queue and write permissions on the dead letter exchange. Permissions are verified at the time of queue declaration.

Routing Dead-Lettered Messages

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

• with the routing key specified for the queue they were on; or, if this was not set,
• with the same routing keys they were originally published with

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

It is possible to form a cycle of message dead-lettering. For instance, this can happen when a queue dead-letters messages to the default exchange without specifying a dead-letter routing key. Messages in such cycles (i.e. messages that reach the same queue twice) will be dropped if there was no rejections in the entire cycle.

Safety

By default, dead-lettered messages are re-published without publisher confirms turned on internally. Therefore using DLX in a clustered RabbitMQ environment is not guaranteed to be safe. Messages are removed from the original queue immediately after publishing to the DLX target queue. This ensures that there is no chance of excessive message buildup that could exhaust broker resources, but messages can be lost if the target queue isn't available to accept messages.

Since RabbitMQ 3.10 quorum queues support at-least-once dead-lettering where messages are re-published with publisher confirms turned on internally.

Dead-Lettered Effects on Messages

Dead-lettering a message modifies its headers:

• the exchange name is replaced with that of the latest dead-letter exchange,
• the routing key may be replaced with that specified in a queue performing dead lettering,
• if the above happens, the CC header will also be removed, and
• the BCC header will be removed as per Sender-selected distribution

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 dead lettering event, identified by a pair of {queue, reason}. Each such entry is a table that consists of several fields:

• queue: the name of the queue the message was in before it was dead-lettered
• reason: reason for dead lettering, see below
• time: the date and time the message was dead lettered as a 64-bit AMQP 0-9-1 timestamp
• exchange - the exchange the message was published to (note that this will be a dead letter exchange if the message is dead lettered multiple times)
• routing-keys: the routing keys (including CC keys but excluding BCC ones) the message was published with
• count: how many times this message was dead-lettered in this queue for this reason
• original-expiration (if the message was dead-lettered due to per-message TTL): the original expiration property of the message. The expiration property is removed from the message on dead-lettering in order to prevent it from expiring again in any queues it is routed to.

New entries are prepended to the beginning of the x-death array. In case x-death already contains an entry with the same queue and dead lettering reason, its count field will be incremented and it will be moved to the beginning of the array.

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

• rejected: the message was rejected with requeue parameter set to false
• expired: the message TTL has expired
• maxlen: the maximum allowed queue length was exceeded
• delivery_limit: the message has been returned more times than the limit (set by policy argument delivery-limit of quorum queues).

Three top-level headers are added for the very first dead-lettering event. They are

• x-first-death-reason
• x-first-death-queue
• x-first-death-exchange

They have the same values as the reason, queue, and exchange fields of the original dead lettering event. Once added, these headers are never modified.

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