Dead Letter Exchanges
What is a Dead Letter Exchange
Messages from a queue can be "dead-lettered", which means these messages are republished to an exchange when any of the following events occur.
- The message is negatively acknowledged by a consumer using
requeueparameter set to
- The message expires due to per-message TTL, or
- The message is dropped because its queue exceeded a length limit
Note that if a queue expires, the messages in the queue are not "dead-lettered".
Dead letter exchanges (DLXs) are normal exchanges. They can be any of the usual types and are declared as normal.
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.
Configuring a Dead Letter Exchange using a Policy
To specify a DLX using policy, add the key "dead-letter-exchange" to a policy definition. For example:
The previous policy applies the DLX "my-dlx" to all queues. This is an example only, in practice, different sets of queues usually 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.
Configuring a Dead Letter Exchange using Optional Queue Arguments
To set the DLX for a queue, specify
x-dead-letter-exchange argument when
declaring the queue. The value must be an exchange name in
the same virtual host:
Map<String, Object> args = new HashMap<String, Object>();
channel.queueDeclare("myqueue", false, false, false, args);
The previous code declares a new exchange called
some.exchange.name and sets this new exchange
as the dead letter exchange for a newly created queue.
Note, 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 are silently dropped.
You may also specify a routing key to use when the messages are being dead-lettered. If the routing key is not set, the message's own routing keys are used.
When a dead letter exchange is specified, in addition to the usual configure permissions on the declared queue, the user must have read permissions on that queue and write permissions on the dead letter exchange. Permissions are verified at the time the queue is declared.
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 a
routing key, and that message is
dead-lettered, it is published to its dead letter
exchange with the
foo routing key. If the queue
the message originally landed on is declared with
x-dead-letter-routing-key set to
bar, then the message is published to
its dead letter exchange with the
bar routing key.
Note, 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
(refer to Sender-selected distribution for details about 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 (that is, messages that reach the same queue twice) are dropped if there was no rejections in the entire cycle.
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 build up that could exhaust broker resources. However, messages can be lost if the target queue is not 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
CCheader will also be removed, and
BCCheader will be removed as per Sender-selected distribution
The dead-lettering process adds an array to the header of
each dead-lettered message named
This array contains an entry for each dead lettering event, which is
identified by a pair of
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: the reason for dead lettering (desribed further 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, this is a dead letter exchange if the message is dead lettered multiple times)
routing-keys: the routing keys (including
CCkeys but excluding
BCCones) 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
expirationproperty of the message. The
expirationproperty is removed from the message on dead-lettering to prevent it from expiring again in any queues it is routed to.
New entries are prepended to the beginning of the
array. In the case where
x-death already contains an entry with
the same queue and dead lettering reason, it's count field is
incremented and it is moved to the beginning of the array.
reason is a name describing why the
message was dead-lettered and is one of the following:
rejected: the message was rejected with the
requeueparameter set to
expired: the message TTL has expired
maxlen: the maximum allowed queue length was exceeded
delivery_limit: the message is 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
They have the same values as the
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 is recorded in the first entry.