Poison messages and dead-letter queues
A poison message is one that always fails processing — malformed data, a bug, a missing record. Retried forever, it wastes consumer capacity and can block other messages.
What causes it
Queues redeliver failed messages so transient errors recover. A message that will never succeed just loops. A dead-letter queue (DLQ) catches it after a maximum number of receives so the rest of the queue keeps flowing and someone can inspect it later.
How to recognise it
- The same message failing repeatedly
- Messages appearing in the dead-letter queue
- Throughput dropping while consumers stay busy
Error messages you will see
| Error | Seen in |
|---|---|
Moved to dead-letter queue (maxReceiveCount exceeded) | Amazon SQS |
How to fix it
- Inspect the dead-letter queue
- Fix the consumer bug
- Lower max receives so bad messages stop blocking
Reproduce it in the simulator
Open the simulator, build a small architecture and use Fault injection in the inspector, or push traffic past a component’s capacity.
Learn more
Part of the guide Message queues vs event streams.