# 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:StartMessageMoveTask` on the dead-letter queue, and `queue:SendMessage` on
  every queue the messages go to. Both are checked before anything moves; without the second the
  redrive is refused with `403`.
- In the console, also `queue:GetQueueAttributes` on the dead-letter queue to open its page
  (without it the page is not found).

## Redrive the messages

**Console**
1. 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.
2. 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:StartMessageMoveTask` on 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."

**CLI**
```sh
dcloud queue queues redrive my-queue-dlq
```

To move every message to one queue instead: `--destination my-queue`.

**API**
```http
POST /queue/api/queues/my-queue-dlq/redrive
{}
```

To move every message to one queue instead:

```http
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`.

**Terraform:** not available. 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](use-an-sqs-client.md). 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.

## Related

- [Dead-letter queues](dead-letter-queues.md)
- [Set a dead-letter queue](set-a-dead-letter-queue.md)
