Dead-letter queues
A dead-letter queue takes a message that has been received a set number of times without being deleted, so one broken message cannot be retried forever.
A dead-letter queue is an ordinary queue of your organization, in the same region, that another queue names as its dead-letter queue together with a maximum receive count from 1 to 1000. A queue cannot be its own dead-letter queue, and a FIFO queue's dead-letter queue must be FIFO, a standard queue's standard. Several queues can share one dead-letter queue.
The API, the CLI and Terraform create a queue without a dead-letter queue unless you name one. The console's Create queue dialog creates one by default; see Create a queue.
When a message moves
Once a message has been received the maximum receive count times and its visibility timeout ends without a delete, it is no longer delivered from its queue. It moves to the dead-letter queue at the next receive on its queue, or within about a minute when nobody is receiving.
In the dead-letter queue the message:
- is receivable at once, with its receive count back at 0;
- keeps its expiry: it is removed when the retention of the queue it was sent to runs out, whatever the dead-letter queue's own retention;
- remembers which queue it came from, which a redrive uses to
send it back. An SQS client sees that queue as
DeadLetterQueueSourceArn.
A FIFO message keeps its group and its order, and joins the end of the dead-letter queue.
Seeing dead-lettered messages
The source queue counts the messages it moved that are still in its dead-letter queue: in the
queue list under In the DLQ, and on its Overview under Dead-lettered. The API reports
the same number as messages.deadLettered.
Rules that follow
- A queue that another queue uses as its dead-letter queue cannot be deleted; remove it from that queue first. See Delete a queue.
- Purging a queue does not touch the messages it moved to its dead-letter queue.