Dead-Letter Queues

Dead-Letter Queues

A dead-letter queue (DLQ) is where a broker sends messages that could not be delivered or processed — for example, because a consumer rejected them, they expired, or the target queue reached its length limit.

HZN Queue Console provides first-class support for working with DLQs: inspecting why messages were dead-lettered, and routing them back for reprocessing with a few clicks.

Identifying a DLQ

DLQs are regular queues. Common naming conventions include:

  • *.dlq, *.dead, *.dlx
  • dead.letter.*
  • Anything configured as the x-dead-letter-exchange or x-dead-letter-routing-key destination on another queue

Open a queue in the browser and look for x-death headers in the message detail panel — their presence confirms a message was dead-lettered.

Reading x-death Headers

When RabbitMQ dead-letters a message it adds an x-death header array. Each entry records:

FieldMeaning
reasonWhy the message was dead-lettered: rejected, expired, maxlen, delivery-limit
queueThe queue the message came from
exchangeThe exchange it was originally published to
routing-keysThe routing keys used
countHow many times this message has been dead-lettered
timeWhen it was dead-lettered

Select a message and expand the Headers section in the detail panel to read these values.

Rescuing Messages

To re-publish dead-lettered messages back to the original queue:

  1. Open the DLQ in the Queue Browser.
  2. Select one or more messages (or select all).
  3. Click Route to queue.
  4. Choose the target queue — typically the queue named in the x-death[*].queue header.
  5. Click Route.

HZN Queue Console automatically strips x-death headers before re-publishing, so the broker does not immediately dead-letter the message again.

Bulk Rescue

To rescue all messages in a DLQ at once, use the select-all checkbox in the message table header, then follow the routing steps above. If the queue has more messages than your current fetch limit, increase the fetch count first using the rows-per-page control.

Purging a DLQ

If you want to discard all messages in a DLQ without rescuing them, click Purge queue in the queue toolbar. This is irreversible.

Preventing Re-Dead-Lettering

After routing a message back, make sure the underlying consumer issue is resolved before the message is processed again. Common causes:

  • Consumer throwing an unhandled exception → fix the consumer code
  • Schema mismatch → update the consumer or use schema validation to inspect the message first
  • Queue policy (TTL, max-length) → adjust the policy if the queue was purged due to length limits