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

URL: https://www.devopsness.com/blog/dead-letter-queues
Author: Kiril Urbonas
Published: 2026-08-16
Updated: 2026-10-31
Categories: DevOps
Tags: Dead Letter Queue, Message Queues, Reliability, Event-Driven, Backend

Summary: A practical guide to dead-letter queues, the pattern that isolates poison messages so one bad payload can't stall your whole pipeline.

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

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]
> 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](/blog/event-driven-architecture-guide), 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](/blog/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](/blog/kafka-partition-strategies-scaling-consumers) 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](/blog/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

- [AWS docs: Using dead-letter queues in Amazon SQS](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-dead-letter-queues.html)
- [AWS CLI reference: sqs start-message-move-task](https://docs.aws.amazon.com/cli/latest/reference/sqs/start-message-move-task.html)
- [RabbitMQ docs: Quorum queues (delivery limit and dead lettering)](https://www.rabbitmq.com/docs/quorum-queues)
- [Spring for Apache Kafka: Publishing dead-letter records](https://docs.spring.io/spring-kafka/reference/kafka/annotation-error-handling.html)

