---
title: "Replay dead letters with a written · Agent Wranglers"
url: https://agentwranglers.se/playbook/events/background-jobs-and-queues/dead-letter-replay
id: EVT-24
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 1016
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Replay dead letters with a written procedure

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Background jobs and queues](https://agentwranglers.se/playbook/events/background-jobs-and-queues.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: EVT-24
- Level: Recommended
- Chapter: [Background jobs and queues](https://agentwranglers.se/playbook/events/background-jobs-and-queues.md)
- Rule: Write one procedure for each dead letter queue. It covers how to read the failures, fix the cause, replay the messages at a capped rate, and record what was replayed or dropped.
- Check: Each dead letter queue has a procedure in the runbook with a named owner. On staging, send 100 messages that fail, fix the cause and run the procedure. All 100 are processed once, the queue is empty, and the log names who replayed them.
- How: A dead letter queue that nobody empties is a slow data loss. Group the failed messages by error first, because one cause usually explains most of them. Fix the code or the data, deploy, then replay. Replay at a capped rate, such as 50 messages a second, so a backlog does not swamp the consumer. Amazon SQS has a redrive task with a maximum rate, and job libraries have a retry command for failed jobs. Replayed messages may be days old, so the consumer must skip what is already done, as [Process each message once](https://agentwranglers.se/playbook/events/consuming-events/idempotent-consumers.md) says. Drop a message only with a written reason, and log who dropped it. Alert when a dead letter queue holds any message for more than 1 day.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Shell example

```bash
# Amazon SQS: move dead letters back to their source queue at 50 messages a second
aws sqs start-message-move-task \
  --source-arn arn:aws:sqs:eu-north-1:111122223333:order-emails-dlq \
  --max-number-of-messages-per-second 50
```

### JavaScript example

```js
const REPLAY_PER_SECOND = 50;

export async function replayFailed(queue, { reason, operator }) {
  const failed = await queue.getFailed();
  for (const [index, job] of failed.entries()) {
    await job.retry();
    if ((index + 1) % REPLAY_PER_SECOND === 0) await new Promise(done => setTimeout(done, 1000));
  }
  log.info({ event: 'dead_letters.replayed', queue: queue.name, count: failed.length, reason, operator });
}
```

### Python example

```python
import time

REPLAY_PER_SECOND = 50

def replay_failed(registry, queue, reason: str, operator: str) -> None:
    job_ids = registry.get_job_ids()
    for index, job_id in enumerate(job_ids, start=1):
        registry.requeue(job_id)
        if index % REPLAY_PER_SECOND == 0:
            time.sleep(1)
    log.info("dead_letters.replayed", queue=queue.name, count=len(job_ids), reason=reason, operator=operator)
```

## Sources

- [Amazon SQS dead-letter queue redrive](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-configure-dead-letter-queue-redrive.html)

## Related rules

- EVT-11 [Process each message once](https://agentwranglers.se/playbook/events/consuming-events/idempotent-consumers.md) in Integration and events

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/events/background-jobs-and-queues/dead-letter-replay">Agent Wranglers integration and events playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Set aside messages that keep failing](https://agentwranglers.se/playbook/events/background-jobs-and-queues/dead-letter-queue.md)
- [Background jobs and queues](https://agentwranglers.se/playbook/events/background-jobs-and-queues.md)