Dead-Letter Queues: Handling Messages That Won't Process
A practical guide to dead-letter queues, the pattern that isolates poison messages so one bad payload can't stall your whole pipeline.
Key takeaways
- A dead letter queue (DLQ) is a separate queue that receives messages your consumers failed to process after a set number of attempts, so one poison message cannot block or loop the main queue.
- Handle it in four steps: alarm when DLQ depth is above zero, inspect the payload and error, fix the cause, then redrive.
On this page
A dead-letter queue (DLQ) is a separate queue where a broker moves messages that failed processing too many times, so one bad message cannot block or endlessly loop the main queue. Good dead letter handling means bounded retries, an alarm on DLQ depth above zero, inspecting the failed payload, fixing the cause, and redriving the messages.
Verified against
Amazon SQS, RabbitMQ 4.4, Spring for Apache Kafka 4.1, against the SQS Developer Guide, the AWS CLI reference, the RabbitMQ dead-letter and quorum queue docs, and the Spring Kafka reference. Checked October 2026.
Every queue-based system eventually meets a message it cannot process: malformed JSON, a deleted record, a permanent 400 from a downstream API. Without a DLQ, that message is picked up, fails, returns, and fails again while everything behind it waits.
What a dead-letter queue is, and why you need one
A DLQ is not special technology. It is an ordinary queue with one job: hold the messages your system gave up on, so they can be inspected later instead of being lost or retried forever. Your primary queue stays reserved for messages with a reasonable chance of succeeding. That matters most in event-driven architecture, where no caller is waiting on the line to notice a failure.
Three things go wrong without one:
Poison messages block the queue. A message that always fails but keeps coming back can stall everything behind it, especially with strict ordering. One bad payload becomes an outage.
Infinite retries burn resources. A consumer retrying a permanently broken message wastes compute, floods logs, and hammers a downstream service that may already be struggling.
Dropped messages destroy evidence. The lazy fix is to catch the error and discard the message. Now you have no payload to reproduce the bug and no way to recover the data.
What sends a message to the DLQ
- Max receive count reached: delivered and returned more times than the configured limit.
- Explicit rejection: the consumer rejects without requeue (RabbitMQ), or code decides the error is permanent.
- TTL expiry: in RabbitMQ an expired message is dead-lettered. SQS just deletes expired messages.
- Queue length limit: RabbitMQ dead-letters messages dropped by a max-length overflow.
The rule that matters is transient versus permanent. Retry with exponential backoff (1 second, then 2, 4, 8) for errors that might clear on their own, like a network blip or a downstream restart. A malformed payload will never parse, so dead-letter known-permanent errors immediately instead of spending the retry budget. Idempotent consumers make all of this safe; see message queue patterns for delivery guarantees.
Amazon SQS: redrive policy, alarm, redrive
SQS attaches the DLQ through a redrive policy with maxReceiveCount. The DLQ must be in the same account and Region as the source, and its type must match (FIFO with FIFO, standard with standard). This creates both queues, wires them, and alarms on the first dead-lettered message:
aws sqs create-queue --queue-name orders-dlq \
--attributes MessageRetentionPeriod=1209600
DLQ_ARN=$(aws sqs get-queue-attributes \
--queue-url "$(aws sqs get-queue-url --queue-name orders-dlq --query QueueUrl --output text)" \
--attribute-names QueueArn --query Attributes.QueueArn --output text)
aws sqs create-queue --queue-name orders \
--attributes '{"RedrivePolicy":"{\"deadLetterTargetArn\":\"'"$DLQ_ARN"'\",\"maxReceiveCount\":\"5\"}"}'
aws cloudwatch put-metric-alarm --alarm-name orders-dlq-not-empty \
--namespace AWS/SQS --metric-name ApproximateNumberOfMessagesVisible \
--dimensions Name=QueueName,Value=orders-dlq \
--statistic Maximum --period 60 --evaluation-periods 1 \
--threshold 0 --comparison-operator GreaterThanThreshold \
--alarm-actions arn:aws:sns:us-east-1:111122223333:oncall
The DLQ gets 14 days of retention (1209600 seconds) on purpose. For standard queues, expiry is based on the original enqueue timestamp, so a message that spent 1 day in the source and lands in a 4-day DLQ disappears after 3 days. AWS recommends DLQ retention longer than the source's. FIFO queues reset the timestamp on the move.
Once the bug is fixed, move messages back to their original source queue:
aws sqs start-message-move-task --source-arn "$DLQ_ARN" \
--max-number-of-messages-per-second 50
{
"TaskHandle": "AQEB6nR4...HzlvZQ=="
}
Only one move task can run per queue at a time, the rate tops out at 500 messages per second, and the source must be a DLQ fed by SQS queues (not Lambda or SNS). Throttle the rate if the consumer you just fixed cannot absorb a burst.
RabbitMQ and Kafka
RabbitMQ uses a dead-letter exchange (DLX): rejected, expired or overflowed messages are republished there. Since RabbitMQ 4.0, quorum queues default to a delivery limit of 20, after which the message is dead-lettered if a DLX is configured, or dropped if not. Set the DLX with a policy rather than hardcoded x-arguments, which cannot change without deleting the queue:
rabbitmqctl set_policy orders-dlx "^orders$" \
'{"dead-letter-exchange":"dlx.orders","dead-letter-routing-key":"orders.failed"}' \
--apply-to queues
Default dead-lettering is at-most-once. Quorum queues can opt into at-least-once dead-lettering, which keeps the message in the source until the target confirms it, at the cost of more memory and CPU.
Kafka has no built-in DLQ, so the convention is an error topic. In Spring Kafka, DefaultErrorHandler defaults to FixedBackOff(0L, 9), ten attempts with no delay, and then only logs the record. Pass it a DeadLetterPublishingRecoverer and the record goes to <originalTopic>-dlt on the same partition, with headers for the exception, original topic, partition and offset. The DLT therefore needs at least as many partitions as the source; Kafka partition strategies covers why that matters when you scale. The gap between a native DLX and a hand-built error topic is one of the bigger operational differences in Kafka vs RabbitMQ.
Failure modes, with the errors you will see
PRECONDITION_FAILED - inequivalent arg 'x-dead-letter-exchange' for queue 'orders'. Your code redeclared a queue with different arguments than it was created with. Remove the argument from the declaration and use a policy, which can change at any time.
The SQS DLQ is filling with messages that succeed on redrive. maxReceiveCount is too low or the visibility timeout is shorter than processing time, so slow but healthy messages get received again and counted as failures. Raise the visibility timeout first.
Spring Kafka hot-loops ten times in milliseconds, then logs and moves on. That is the default FixedBackOff(0L, 9) with no recoverer. Add a real backoff and a DeadLetterPublishingRecoverer, or the record is skipped with nothing but a log line.
Messages vanish from an SQS DLQ before anyone looks. Retention on the DLQ is shorter than, or equal to, the source's. Set it to the 14-day maximum.
Where this breaks
A DLQ fixes isolation, not correctness. If a downstream outage dead-letters 100,000 messages, redriving them all at once can knock it over again, and a non-idempotent consumer will double-apply anything that partially succeeded. On FIFO queues where order matters, AWS advises against a DLQ at all, because moving one message aside lets later ones process first.
Questions people ask
What is dead letter handling?
It is the policy for messages that keep failing: how many times to retry, when to stop, where the message goes, and who gets told. In practice that means a bounded retry count with backoff, a DLQ as the destination, an alarm on DLQ depth above zero, failure metadata attached to each message, and a documented redrive procedure someone has actually run.
What is a good maxReceiveCount for SQS?
Usually 3 to 5. AWS notes that a value as low as 1 sends a message to the DLQ after a single failed receive, so transient errors never get a retry. Very high values only delay the alarm while a poison message keeps cycling. Before raising it, check that the visibility timeout is longer than your slowest successful processing time.
How do I move messages from an SQS DLQ back to the main queue?
Use DLQ redrive: use the DLQ redrive option in the SQS console, or run aws sqs start-message-move-task --source-arn <dlq-arn>. Without a destination ARN, messages return to their original source queues. One move task can run per queue at a time, at up to 500 messages per second. Fix the consumer bug first, or the messages land straight back in the DLQ.
The call we'd make
Add a DLQ to any queue whose messages matter, from day one. It costs almost nothing to configure and it is the difference between a contained failure and a stalled pipeline you discover from customer complaints. Set maxReceiveCount to about 5, give the DLQ longer retention than the source, alarm on depth above zero, and dead-letter known-permanent errors on the first failure. A DLQ only earns its keep if someone looks at it, so the alarm matters more than the queue.
Sources
Cite this article
Kiril Urbonas (2026). Dead-Letter Queues: Handling Messages That Won't Process. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/dead-letter-queues
[Dead-Letter Queues: Handling Messages That Won't Process](https://www.devopsness.com/blog/dead-letter-queues) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)
More from DevOps
Explore more articles in this category
Practical Guide: Incident Response for Platform Teams
Platform teams own the systems that EVERY service depends on. An incident response playbook for when the foundation cracks.
Observability with OpenTelemetry: Traces, Metrics, and Logs
Unify traces, metrics, and logs with OpenTelemetry. Instrumentation, sampling, and backend-agnostic pipelines.
Talos Linux vs Standard Kubernetes Nodes: What Changes When SSH Is Gone
Talos Linux has no SSH, no shell and no package manager. Every node change goes through one mTLS API. Here is what day-2 work looks like without a login, where Talos beats Ubuntu plus kubeadm, and where it will hurt.
You might have missed
Evergreen posts worth revisiting.