Skip to content
Recuro Docs

Using the Dead Letter Queue

The dead-letter queue (DLQ) holds jobs that have exhausted all retry attempts. It gives you a chance to inspect what went wrong, fix the issue, and replay the jobs.

When jobs land in the DLQ

A job is moved to the DLQ when:

  1. The job fails (HTTP error, timeout, assertion failure, etc.)
  2. The queue has retries enabled
  3. All retry attempts are exhausted (default: 3 retries)
  4. The job is marked with final_status: dead_lettered and a dead_lettered_at timestamp

If retries are disabled on the queue, failed jobs are marked as failed_no_retries and do not enter the DLQ.

Viewing the DLQ

  1. Navigate to Dead Letter Queue in the sidebar
  2. The DLQ shows all dead-lettered jobs across all queues
  3. Filter by queue or search by URL
  4. Each entry shows the job URL, queue, failure reason, attempt count, and when it was dead-lettered

Replaying a job

Replaying creates a brand-new job with the same configuration (URL, method, headers, payload) and attempt_number: 1. The new job is dispatched immediately.

Single replay

  1. Find the job in the DLQ
  2. Click Replay

Bulk replay

  1. Select multiple jobs using the checkboxes
  2. Click Bulk Replay

Purging jobs

Purging permanently deletes a dead-lettered job and its run history.

Single purge

  1. Find the job in the DLQ
  2. Click Purge

Bulk purge

  1. Select multiple jobs using the checkboxes
  2. Click Bulk Purge

Automatic cleanup

Dead-lettered jobs are automatically deleted after the queue’s dlq_retention_days:

RetentionDescription
3 daysAggressive cleanup
7 daysShort retention
14 days (default)Standard retention
30 daysExtended retention

The cleanup runs daily. Configure retention per queue from Queues > [queue] > Edit.

DLQ workflow

A typical workflow for handling dead-lettered jobs:

  1. Investigate: Check the failure reason and run details. Is the endpoint down? Is it returning errors?
  2. Fix the root cause: Deploy a fix to your endpoint, update credentials, fix DNS, etc.
  3. Replay: Once the root cause is fixed, replay the dead-lettered jobs
  4. Monitor: Check that the replayed jobs succeed
  5. Purge: Clean up any jobs that are no longer relevant

Next steps

  • Jobs — Understand the full job lifecycle and retry chain
  • Queues — Configure retry delays and DLQ retention
  • Retry Strategy Design — Choose the right retry configuration