Dead-Letter Queue

A dead-letter queue (DLQ) is a secondary queue for messages that cannot be processed safely after retries, validation failures, expiration, or routing errors. Moving those messages aside keeps one poison payload from blocking the main stream.

A DLQ is an operational safety net. It does not fix the failure. The owning team still needs to inspect the message, correct the code, data, or downstream dependency, and decide whether replay is safe.

Where it fits

flowchart LR
Broker["Message broker"] --> Consumer["Consumer"]
Consumer -->|"Success"| Ack["Acknowledge"]
Consumer -->|"Transient failure"| Retry["Retry policy"]
Retry --> Consumer
Retry -->|"Retries exhausted"| DLQ["Dead-letter queue"]
DLQ --> Inspect["Inspect and repair"]
Inspect --> Replay["Replay if safe"]

Retries should handle temporary failures such as timeouts. A DLQ handles the cases that need human or automated repair.

Common causes

• Malformed JSON or an unexpected schema version.
• A referenced entity no longer exists.
• A downstream service rejects the operation permanently.
• The consumer has a bug that affects one class of message.
• The message exceeds retry count, age, size, or delivery limit.

Operating a DLQ

Treat DLQs as production queues with ownership.

• Alert on age and count, not only on total volume.
• Preserve the original payload, headers, delivery count, error reason, and trace ID.
• Make replay explicit. Blind replay can repeat the same failure or duplicate side effects.
• Separate transient retry from dead-letter handling. A message should not go to the DLQ on the first timeout.
• Review DLQ volume after deployments. A sudden increase often points to a contract or schema change.

Replay workflow

1. Identify the failure class.
2. Fix the consumer, payload, mapping, or downstream dependency.
3. Check whether the handler is idempotent.
4. Replay a small sample.
5. Monitor side effects, lag, and new DLQ entries.
6. Replay the remaining messages in batches.

Trade-offs

A DLQ protects throughput, but it can also hide data loss if nobody owns it. The system is only reliable when dead-lettered messages are visible, investigated, and either replayed or intentionally discarded.