guide · queue

Dead jobs, from the producer side.

The Queue object carries the DLQ surface too, so the process that produces work can also configure and drain the pile of work that failed.

DLQ operations

The dead letter queue collects jobs that failed permanently (retries exhausted, stalled too often, timed out). Configure how it behaves and act on its entries:

Bun

queue.setDlqConfig({
  autoRetry: true,             // Periodically re-queue DLQ entries
  autoRetryInterval: 3600000,  // Every hour
  maxAutoRetries: 3,
  maxAge: 604800000,           // Drop entries older than 7 days
  maxEntries: 10000,
});

// Synchronous snapshots (embedded mode)
const entries = queue.getDlq();
const stalledJobs = queue.getDlq({ reason: 'stalled' });
const stats = queue.getDlqStats(); // { total, byReason, pendingRetry, ... }

// Authoritative reads (embedded or TCP)
const remoteEntries = await queue.getDlqAsync({ reason: 'stalled' });
const remoteStats = await queue.getDlqStatsAsync();

// Act
queue.retryDlq();           // Retry all
queue.retryDlq('job-123');  // Retry one
queue.purgeDlq();           // Clear all
const retried = await queue.retryDlqByFilterAsync({ reason: 'stalled' });

Node.js / Deno

await queue.setDlqConfig({
  autoRetry: true,             // Periodically re-queue DLQ entries
  autoRetryInterval: 3600000,  // Every hour
  maxAutoRetries: 3,
  maxAge: 604800000,           // Drop entries older than 7 days
  maxEntries: 10000,
});

// Inspect
const entries = await queue.getDlq();

// Act
await queue.retryDlq();           // Retry all
await queue.retryDlq('job-123');  // Retry one
await queue.purgeDlq();           // Clear all

Python

queue.set_dlq_config({
    "autoRetry": True,             # Periodically re-queue DLQ entries
    "autoRetryInterval": 3600000,  # Every hour
    "maxAutoRetries": 3,
    "maxAge": 604800000,           # Drop entries older than 7 days
    "maxEntries": 10000,
})

# Inspect
entries = queue.get_dlq()

# Act
queue.retry_dlq()            # Retry all
queue.retry_dlq("job-123")   # Retry one
queue.purge_dlq()            # Clear all

PHP

// Inspect
$entries = $queue->getDlq();

// Act
$queue->retryDlq();           // Retry all
$queue->retryDlq('job-123');  // Retry one
$queue->purgeDlq();           // Clear all

Go

// Inspect
entries, _ := queue.GetDlq(0) // 0 = server default count

// Act
queue.RetryDlq("", 0)        // Retry all
queue.RetryDlq("job-123", 0) // Retry one
queue.PurgeDlq()             // Clear all

Rust

// Inspect
let entries = queue.get_dlq(None)?;

// Act
queue.retry_dlq(None, None)?;            // Retry all
queue.retry_dlq(Some("job-123"), None)?; // Retry one
queue.purge_dlq()?;                      // Clear all

Elixir

# Inspect
{:ok, entries} = Bunqueue.Queue.dlq(queue)

# Act
{:ok, _count} = Bunqueue.Queue.retry_dlq(queue)             # Retry all
{:ok, _count} = Bunqueue.Queue.retry_dlq(queue, "job-123")  # Retry one
{:ok, _count} = Bunqueue.Queue.purge_dlq(queue)             # Clear all

DLQ configuration (setDlqConfig) is available in Bun, TypeScript, and Python; PHP, Go, Rust, and Elixir can set the same server policy through PUT /queues/:queue/dlq-config. Full metadata, stats, and server-side reason filters exist in the Bun package only; every SDK can use the HTTP metadata and stats endpoints. Automatic retries preserve their bounded retry chain and failure history across redelivery and SQLite-backed broker restarts.

TCP mode

The synchronous getDlq() / getDlqStats() methods are embedded snapshots, and the synchronous mutation forms are fire-and-forget over TCP. Use getDlqAsync(filter?), getDlqStatsAsync(), retryDlqAsync(), retryDlqByFilterAsync(filter), and purgeDlqAsync() when a remote result or count matters. Full entry metadata and every live Job method survive the TCP round trip. getDlqConfigAsync() reads the authoritative server config.

See Dead Letter Queue for the full guide, and Stall Detection for setStallConfig(), which controls when unresponsive jobs are recovered.

Where to go next

Dead Letter Queue	The DLQ guide these operations belong to
DLQ Operations	Filter, retry selectively, check health, purge
DLQ Configuration	Bound the DLQ by age and by entry count
Queue API	Create a queue in embedded or TCP mode
Adding Jobs	add, addBulk, priorities, delays, durability
Deduplication and Idempotent Job Adds	Idempotent adds, dedup keys, custom job ids
Querying Jobs	Fetch jobs, states, counts and results
Queue Control and Maintenance	Pause, drain, obliterate, clean and repair
Progress, Job Logs and Dependencies	Progress, per-job logs and dependencies
Queue Rate Limiting and Global Concurrency	Rate limits and global concurrency caps
Job Schedulers from the Queue	Named repeatable schedules from the queue
Workers, Stats and Metrics from the Queue	Registered workers, stats and metrics windows
Namespaces, Auto-Batching and Store-and-Forward	Namespaces, auto-batching, store-and-forward
JobOptions Reference	Every JobOptions field, with defaults