Handle dead-letter records in a queue
When a queue consumer receives a record MaxReceiveCount times without
acknowledging it, the queue marks the record as a dead-letter record and stops delivering it
on the normal receive path. A record that reaches MaxReceiveCount without an
acknowledgment usually cannot be processed as it stands, and setting it aside stops the
queue from redelivering it to your consumer instances.
Set MaxReceiveCount high enough that a record is unlikely to be processable
by the time it reaches the limit, and low enough that a failing record is set aside before
the queue redelivers it many times. A dead-letter record stays on the same queue, and you
work with it through a separate set of operations: you receive dead-letter records, and then
either acknowledge them or restore them to the normal receive path.
Set an alarm on VisibleDeadLetterQueueRecords so that you learn when
dead-letter records begin to accumulate. Receive the records to inspect why they failed, and
correct the cause in your queue consumer or in a downstream dependency. Then restore the
records so that the queue delivers them again, up to MaxReceiveCount times.
Acknowledge only the records that cannot be processed. For more information about monitoring
dead-letter records, see Monitor a queue.
How dead-letter handling works
Dead-letter handling is built into every queue. By default it is on, and a record becomes a dead-letter record after it is received 6 times without an acknowledgment.
DeadLetterConfiguration is a queue attribute. Set
TargetType to BUILT_IN
to keep it on, or to NONE to turn it off. When you set
TargetType to BUILT_IN, you must also set
MaxReceiveCount, from 1 to 1,000. A queue that you create without
DeadLetterConfiguration gets BUILT_IN with a
MaxReceiveCount of 6.
When dead-letter handling is off, an unacknowledged record keeps being redelivered until it is acknowledged or its retention period ends.
A queue has no retention period of its own. A dead-letter record expires when the stream's retention period ends for that record, the same as any other record in the stream. Correct the cause and restore or acknowledge dead-letter records before the stream's retention period ends. For more information about the retention period, see Change the data retention period.
Work with dead-letter records
Dead-letter records remain on the same queue as its other records, and you work with them through a separate set of operations that use the same queue ARN. Use the following operations:
ReceiveDeadLetterQueueRecords-
Receives a batch of dead-letter records, up to 10 records per call. Each record carries the same fields and delivery metadata as a record on the normal receive path.
AcknowledgeDeadLetterQueueRecords-
Acknowledges dead-letter records, up to 10 records per call. The queue does not deliver an acknowledged record again.
UpdateDeadLetterQueueRecordsVisibility-
Changes the visibility timeout of dead-letter records that are in flight, up to 10 records per call. Set the timeout to 0 to make a record visible again immediately.
RestoreDeadLetterQueueRecords-
Returns dead-letter records to the normal receive path, up to 10 records per call. Restoring a record clears its dead-letter state and resets its receive count.
Example: receive and handle a dead-letter record
The following example receives a dead-letter record, and then acknowledges or restores it. Replace the queue ARN and the receipt handle with your own values.
Receive a dead-letter record:
aws kinesis receive-dead-letter-queue-records \ --queue-arn arn:aws:kinesis:us-east-1:111122223333:queue/resource-id \ --limit 10
The response includes a receipt handle, a record ID, and the receive count. The following is example output.
{ "QueueRecords": [ { "ReceiptHandle": "AQID...example...", "RecordId": "2c455db5cc0161eb3dbac00da1ce9337", "PartitionKey": "user-1234", "Data": "eyJldmVudCI6ICJvcmRlciJ9", "ApproximateArrivalTimestamp": "2026-01-15T10:00:00.000000+00:00", "FirstReceiveTimestamp": "2026-01-15T10:05:00.000000+00:00", "ReceiveCount": 7 } ] }
After you inspect the record, acknowledge it if you have handled it, or restore it to deliver it again after you correct the cause.
Acknowledge the dead-letter record:
aws kinesis acknowledge-dead-letter-queue-records \ --queue-arn arn:aws:kinesis:us-east-1:111122223333:queue/resource-id \ --entries '[ { "ReceiptHandle": "AQID...example..." } ]'
Or restore the dead-letter record:
aws kinesis restore-dead-letter-queue-records \ --queue-arn arn:aws:kinesis:us-east-1:111122223333:queue/resource-id \ --entries '[ { "ReceiptHandle": "AQID...example..." } ]'
The acknowledge and restore operations return Successful and
Failed lists, correlated by ReceiptHandle. Check the
Failed list even when the response returns HTTP 200.