guide · dead letter queue

How long dead jobs stick around.

A DLQ that grows forever is just a leak with extra steps. These options bound it by age and by count, and decide whether entries get another chance before they expire.

Configuration

Bun

queue.setDlqConfig({
  autoRetry: true,
  autoRetryInterval: 3600000,
  maxAutoRetries: 3,
  maxAge: 604800000,   // purge entries after 7 days (null = never)
  maxEntries: 10000,
});

Node.js / Deno

await queue.setDlqConfig({
  autoRetry: true,
  autoRetryInterval: 3600000,
  maxAutoRetries: 3,
  maxAge: 604800000,   // purge entries after 7 days (null = never)
  maxEntries: 10000,
});

Python

# Config keys are the wire names (camelCase)
queue.set_dlq_config({
    "autoRetry": True,
    "autoRetryInterval": 3600000,
    "maxAutoRetries": 3,
    "maxAge": 604800000,   # purge entries after 7 days (None = never)
    "maxEntries": 10000,
})

PHP

$queue->connection->call([
    'cmd' => 'SetDlqConfig',
    'queue' => $queue->name,
    'config' => [
        'autoRetry' => true,
        'autoRetryInterval' => 3600000,
        'maxAutoRetries' => 3,
        'maxAge' => 604800000,
        'maxEntries' => 10000,
    ],
]);

Go

_, err := queue.Connection.Call(map[string]any{
    "cmd":   "SetDlqConfig",
    "queue": queue.Name,
    "config": map[string]any{
        "autoRetry":         true,
        "autoRetryInterval": 3600000,
        "maxAutoRetries":    3,
        "maxAge":            604800000,
        "maxEntries":        10000,
    },
})
if err != nil {
    log.Fatal(err)
}

Rust

use bunqueue_client::{Connection, ConnectionOptions, Value};

let connection = Connection::new(ConnectionOptions::default());
connection.call(vec![
    (Value::from("cmd"), Value::from("SetDlqConfig")),
    (Value::from("queue"), Value::from("emails")),
    (Value::from("config"), Value::Map(vec![
        (Value::from("autoRetry"), Value::from(true)),
        (Value::from("autoRetryInterval"), Value::from(3_600_000)),
        (Value::from("maxAutoRetries"), Value::from(3)),
        (Value::from("maxAge"), Value::from(604_800_000)),
        (Value::from("maxEntries"), Value::from(10_000)),
    ])),
])?;

Elixir

{:ok, _response} =
  Bunqueue.Queue.call(queue, %{
    "cmd" => "SetDlqConfig",
    "queue" => queue.name,
    "config" => %{
      "autoRetry" => true,
      "autoRetryInterval" => 3_600_000,
      "maxAutoRetries" => 3,
      "maxAge" => 604_800_000,
      "maxEntries" => 10_000
    }
  })

The DLQ policy is server-side state per queue: set it once from any client and it governs jobs failed by workers in every language. A dedicated helper ships in the Bun package, the TypeScript SDK and the Python SDK; the other tabs issue the same SetDlqConfig command through each SDK’s public TCP connection.

Confirming the write in TCP mode

In the Bun client setDlqConfig() is fire-and-forget over TCP: it updates the local cache and sends the command without waiting, so a transport failure is not reported to you. Use await queue.setDlqConfigAsync(config) when you need the call to resolve only once the server has applied the policy. In embedded mode the two are equivalent.

Option	Default	Description
autoRetry	false	Enable automatic retry
autoRetryInterval	3600000	Base delay between auto-retries (1 hour)
maxAutoRetries	3	Maximum auto-retry attempts
maxAge	604800000	Auto-purge age (7 days, null = never)
maxEntries	10000	Maximum DLQ entries per queue

Where to go next

DLQ Operations from the Queue Object	The same operations from an existing Queue instance
Dead Letter Queue	What the DLQ is, and a first look at what failed
DLQ Operations	Filter, retry selectively, check health, purge
Automatic DLQ Retry with Backoff	Let bunqueue re-queue dead entries on a backoff
DLQ Reference	Failure reasons, entry shape, every DLQ method