# Add a dead-letter queue for messages that will never succeed

A poison message looping forever, given somewhere to go after a bounded number of attempts.

Category: Queues, jobs, and async work
Source: https://letsship.ai/use-cases/add-a-dead-letter-queue
Published: 2026-08-25

## Goal

Add a dead-letter queue so permanently failing messages stop retrying.

## Acceptance criteria

- Messages move to the letter queue after a stated attempt count
- A poison message is seeded and observed arriving there
- The letter queue has an alert on depth
- The original failure reason is preserved with the message

## What lands as proof

A seeded poison message observed landing in the letter queue rather than cycling.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Add a dead-letter queue to {queue}

Description: Add a dead-letter queue so permanently failing messages stop retrying.

Acceptance criteria:
- Messages move to the letter queue after a stated attempt count
- A poison message is seeded and observed arriving there
- The letter queue has an alert on depth
- The original failure reason is preserved with the message

Before you create the issue, check which of this repository's queues have no dead-letter configuration and replace {queue}.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: add a dead-letter queue so permanently failing messages stop retrying. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means a poison message lands in the letter queue instead of looping forever, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.