Skip to main content
Dead-Letter Queues: Handling Messages That Won't Process

Dead-Letter Queues: Handling Messages That Won't Process

KU
· Founder & Chief Editor
• 8 min read•Updated •

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.

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:

Terminal
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:

Terminal
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:

Terminal
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

Explore topics:DevOps
React
Share this post
Cite this article
Plain text

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

Markdown

[Dead-Letter Queues: Handling Messages That Won't Process](https://www.devopsness.com/blog/dead-letter-queues) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)

KU

Kiril Urbonas

Founder & Chief Editor

608 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.