Dead-letter queue

What is a dead-letter queue?

A dead-letter queue, or DLQ, is a separate queue for messages a system could not process. When a message fails repeatedly, or sits too long unhandled, the broker moves it out of the main flow into the DLQ, and everything behind it keeps moving.

The problem it solves is the poison message: one malformed message a consumer picks up, fails on, and receives again in a loop. That single message can stall an entire message queue. A DLQ is the backstop behind your retry policy: once the retries, usually spaced out with exponential backoff, are used up, the message is set aside instead of looping forever.

When does a message get dead-lettered?

On Amazon SQS, dead-lettering runs on a single counter. You attach a redrive policy to the source queue with a maxReceiveCount, say 5. Each time a consumer receives a message and fails to delete it the receive count climbs, and once it passes that limit SQS moves the message to the DLQ.

Azure Service Bus is stricter and dead-letters on several distinct conditions beyond a retry count:

• Delivery count exceeded. The default maximum delivery count is 10. A message abandoned or whose lock expires that many times moves to the DLQ with the reason MaxDeliveryCountExceeded.

• Message expiry. With dead-lettering on expiration enabled, a message that outlives its time-to-live is moved with the reason TTLExpiredException, even if no consumer ever touched it.

• Other broker conditions. An oversized header, a null session id on a session-enabled entity, or a subscription filter-rule error.

• Explicit rejection. Your own code can dead-letter a message it knows is malformed or unauthorised.

RabbitMQ reaches the same outcome through a dead letter exchange, triggered by a reject with requeue set to false, a per-message TTL expiry, a queue length limit, or exceeding the delivery-limit on a quorum queue.

Dead-letter queue versus error log

A DLQ is easy to confuse with an error log, but the difference is recovery. A log records what failed and why; a DLQ keeps the failed message itself, so once you fix the cause it is already there to reprocess. That matters because brokers usually guarantee at-least-once delivery and redeliver a message several times before it ever lands in the DLQ.

What to watch out for with dead-letter queues

A DLQ is a diagnostic and recovery tool, not a bin.

• An unmonitored DLQ is a silent outage. Failed orders or invoices pile up while every dashboard stays green. Alert on the count and age of the oldest message; SQS can raise a CloudWatch alarm the moment one arrives. Treat it as a data observability signal and give a critical queue a named owner.

• Redrive only after you fix the cause. SQS calls moving messages back to the source queue a redrive; Azure operators do it from Service Bus Explorer. Replaying while the bug is still live just sends the message straight back.

• Make reprocessing idempotent. A redriven message may have been half-processed the first time. Idempotence keeps the replay from charging a customer twice or writing a duplicate row.