Redrive a dead-letter queue
Once you have fixed what made messages fail, move a dead-letter queue's messages back to the queues they failed in, or all of them to one queue.
Replace my-queue-dlq with the name of the dead-letter queue.
Prerequisites
- Permission for
queue:StartMessageMoveTaskon the dead-letter queue, andqueue:SendMessageon every queue the messages go to. Both are checked before anything moves; without the second the redrive is refused with403. - In the console, also
queue:GetQueueAttributeson the dead-letter queue to open its page (without it the page is not found).
Redrive the messages
- Open the dead-letter queue. Its Overview has a Dead-letter redrive section (on a queue that another queue names as its dead-letter queue, or that holds dead-lettered messages), which names the queues its messages came from.
- Choose Redrive to source.
The section then says how many messages moved back, and how many stayed. The console sends every message back to the queue it came from; to choose another destination, use the CLI or the API.
Redrive to source is unavailable:
- without
queue:StartMessageMoveTaskon the queue: the section says "Redriving needs queue:StartMessageMoveTask on this queue and queue:SendMessage on the source queues. Ask an administrator."; - when no message in the queue came from a queue that still exists: "No message here came from another queue, so there is nothing to send back."
dcloud queue queues redrive my-queue-dlqTo move every message to one queue instead: --destination my-queue.
POST /queue/api/queues/my-queue-dlq/redrive
{}To move every message to one queue instead:
POST /queue/api/queues/my-queue-dlq/redrive
{ "destination": "my-queue" }The answer is 200 when the redrive has finished, with taskId, status, moved, remaining,
startedAt and finishedAt.
Not available in Terraform. A redrive is an action, not configuration.
From an SQS client, call StartMessageMoveTask with the dead-letter queue's ARN as SourceArn
(and optionally a DestinationArn); see Use an SQS client. It answers
TaskHandle once the redrive has finished, and ResourceNotFoundException when either queue does
not exist.
Result
The redrive runs to completion before the call returns, moving at most 100,000 messages per call. Each moved message arrives as a new delivery: receivable at once, with its receive count at 0 and its original expiry. A receipt handle from an earlier receive no longer works on it.
These stay in the dead-letter queue, and remaining counts them:
- messages that are in flight in the dead-letter queue (someone received them);
- messages past their retention that have not been removed yet;
- without a destination, messages whose source queue has been deleted, and messages sent to the dead-letter queue directly rather than moved there;
- what is left after the 100,000 messages one call moves; redrive again for the rest.
On a FIFO dead-letter queue, messages leave in order and join the end of their destination in that order; a message group with a message in flight in the dead-letter queue stays there whole.
When a redrive is refused
400"The destination must be another queue."400"A redrive moves messages between queues of one type: FIFO to FIFO, standard to standard."404"There is no queue named “my-queue” here." when the destination does not exist.