Failed jobs, kept in the DLQ.

When a job runs out of retries, bunqueue can retain it in the Dead Letter Queue with the terminal error and attempt metadata, so you can inspect it and retry it deliberately.

The Dead Letter Queue (DLQ) is a holding area for jobs that failed permanently, for example after exhausting all retry attempts. Unless removeOnFail is set, each entry keeps the original job, its terminal error, and a complete ordered array of AttemptRecord values. The history includes retryable failures before the terminal attempt and remains attached across automatic DLQ redeliveries.

Entries are not permanent by definition: maxAge, maxEntries, an explicit purge, or Queue.obliterate() can remove them. The defaults retain entries for seven days and cap each queue at 10,000 entries. Capacity eviction removes the oldest entry from memory and SQLite together, including its terminal ownership and stored result/log data.

Quick Start

import { Queue } from 'bunqueue/client';

const queue = new Queue('emails', { embedded: true });

// See what failed and why
const entries = queue.getDlq();
for (const entry of entries) {
  console.log(entry.job.id, entry.reason, entry.error);
}

// Put everything back in the queue for another try
queue.retryDlq();

import { Queue } from 'bunqueue-client';

const queue = new Queue('emails');

// List the dead jobs (over TCP they arrive as plain jobs,
// without DLQ metadata like the failure reason)
const jobs = await queue.getDlq();
for (const job of jobs) {
  console.log(job.id);
}

// Put everything back in the queue for another try
await queue.retryDlq();

from bunqueue import Queue

queue = Queue("emails")

# List the dead jobs (over TCP they arrive as plain jobs,
# without DLQ metadata like the failure reason)
for job in queue.get_dlq():
    print(job["id"])

# Put everything back in the queue for another try
queue.retry_dlq()

use Bunqueue\Queue;

$queue = new Queue('emails');

// List the dead jobs (over TCP they arrive as plain jobs,
// without DLQ metadata like the failure reason)
foreach ($queue->getDlq() as $job) {
    echo $job['id'], PHP_EOL;
}

// Put everything back in the queue for another try
$queue->retryDlq();

queue := bunqueue.NewQueue("emails", bunqueue.Options{})
defer queue.Close()

// List the dead jobs (over TCP they arrive as plain jobs,
// without DLQ metadata like the failure reason)
jobs, err := queue.GetDlq(0)
for _, job := range jobs {
    fmt.Println(job["id"])
}

// Put everything back in the queue for another try
_, err = queue.RetryDlq("", 0)

use bunqueue_client::{ConnectionOptions, Queue};

let queue = Queue::new("emails", ConnectionOptions::default());

// List the dead jobs (over TCP they arrive as plain jobs,
// without DLQ metadata like the failure reason)
let jobs = queue.get_dlq(None)?;
println!("{} dead jobs", jobs.len());
for job in &jobs {
    println!("{job:?}");
}

// Put everything back in the queue for another try
queue.retry_dlq(None, None)?;

queue = Bunqueue.queue("emails")

# List the dead jobs (over TCP they arrive as plain jobs,
# without DLQ metadata like the failure reason)
{:ok, jobs} = Bunqueue.Queue.dlq(queue)
for job <- jobs, do: IO.puts(job["id"])

# Put everything back in the queue for another try
{:ok, _count} = Bunqueue.Queue.retry_dlq(queue)

From the CLI, against a running server:

bunqueue dlq list emails
bunqueue dlq retry emails
bunqueue dlq purge emails

Where to go next


DLQ Operations from the Queue Object	The same operations from an existing Queue instance
DLQ Operations	Filter, retry selectively, check health, purge
Automatic DLQ Retry with Backoff	Let bunqueue re-queue dead entries on a backoff
DLQ Configuration	autoRetry, maxAge, maxEntries and the defaults
DLQ Reference	Failure reasons, entry shape, every DLQ method