# DLQ Configuration: Size, Age and Retry Policy

Every setDlqConfig option for the bunqueue Dead Letter Queue: automatic retry, base interval, retry ceiling, entry expiry and the per-queue entry cap, with defaults.

Canonical: https://bunqueue.dev/guide/dlq/configuration/

---

import { Tabs, TabItem } from '@astrojs/starlight/components';

<div class="bq-wrap bq-hero">
  <span class="bq-eyebrow">guide · dead letter queue</span>
  <h1 class="bq-hero-h1 bq-bench-h1">How long dead jobs <em>stick around.</em></h1>
  <p class="bq-hero-sub">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.</p>
</div>

## Configuration

<Tabs syncKey="lang">
<TabItem label="Bun">

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

</TabItem>
<TabItem label="Node.js / Deno">

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

</TabItem>
<TabItem label="Python">

```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,
})
```

</TabItem>
<TabItem label="PHP">

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

</TabItem>
<TabItem label="Go">

```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)
}
```

</TabItem>
<TabItem label="Rust">

```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)),
    ])),
])?;
```

</TabItem>
<TabItem label="Elixir">

```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
    }
  })
```

</TabItem>
</Tabs>

*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.*

:::note[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](/guide/queue/dlq/) | The same operations from an existing Queue instance |
| [Dead Letter Queue](/guide/dlq/) | What the DLQ is, and a first look at what failed |
| [DLQ Operations](/guide/dlq/operations/) | Filter, retry selectively, check health, purge |
| [Automatic DLQ Retry with Backoff](/guide/dlq/auto-retry/) | Let bunqueue re-queue dead entries on a backoff |
| [DLQ Reference](/guide/dlq/reference/) | Failure reasons, entry shape, every DLQ method |