nself dlq

Inspect and manage dead-letter queues backed by Redis (BullMQ and the ɳClaw job system). Pairs with nself queue for live queue management.

Quick start

# List all failed jobs across all queues
nself dlq list

# Retry a specific failed job
nself dlq retry 7f3a9c

# Replay a job with its original payload
nself dlq replay 7f3a9c

# Purge all jobs from the DLQ
nself dlq purge

Synopsis

nself dlq <SUBCOMMAND> [FLAGS]

Description

When a BullMQ job fails after all retry attempts, nSelf moves it to a dead-letter queue (DLQ). The DLQ is a Redis key scoped to the originating queue name. nself dlq gives you a CLI interface to inspect failed jobs, retry them one at a time, replay them with the original payload for debugging, or purge the entire DLQ.

The ɳClaw memory and pipeline jobs have their own DLQ separate from the generic BullMQ queues. nself dlq surfaces both. Use --queue to scope to a specific queue.

DLQ operations require Redis to be running. If Redis is not enabled in your config, these commands return an error. Enable Redis with nself service enable redis.

Subcommands

nself dlq list

List failed jobs in the dead-letter queue, newest first.

nself dlq list
# ID        QUEUE              FAILED AT            ATTEMPTS   ERROR
# 7f3a9c    email-send         2026-05-07 14:21     3/3        SMTP connection refused
# 4b2d1e    claw-memory        2026-05-07 13:05     3/3        pgvector insert timeout
# a9c3f0    notify-push        2026-05-06 22:44     3/3        FCM 401 Unauthorized

# Scope to one queue
nself dlq list --queue email-send

# JSON output for scripting
nself dlq list --json

nself dlq retry <id>

Move a failed job back to its original queue for immediate re-processing.

nself dlq retry 7f3a9c
# ✓ Job 7f3a9c moved back to queue email-send

nself dlq replay <id>

Print the original job payload for inspection, then optionally re-enqueue it. Useful for debugging why a job failed — inspect the data without committing to a retry.

nself dlq replay 7f3a9c
# Payload:
# {
#   "to": "user@example.com",
#   "subject": "Welcome to ɳSelf",
#   "template": "welcome"
# }
# Re-enqueue this job? [y/N]

nself dlq purge

Delete all jobs from the dead-letter queue. Prompts for confirmation unless --yes is passed.

nself dlq purge
# This will delete 47 failed jobs. Continue? [y/N] y
# ✓ DLQ purged (47 jobs removed)

# Purge a specific queue's DLQ
nself dlq purge --queue claw-memory

# Skip confirmation
nself dlq purge --yes

Flags

Examples

Find and retry all email failures

# List failures in the email queue
nself dlq list --queue email-send --json | jq '.[].id' -r | while read id; do
  nself dlq retry "$id"
done

Inspect a failed ɳClaw memory job

nself dlq list --queue claw-memory
nself dlq replay 4b2d1e

Monitor DLQ growth over time (CI alert)

count=$(nself dlq list --json | jq length)
if [ "$count" -gt 10 ]; then
  echo "DLQ has $count failed jobs — investigate" && exit 1
fi

Environment variables

• REDIS_URL — Redis connection string (default read from active environment config)
• NSELF_DLQ_PREFIX — BullMQ key prefix (default: bull)

Exit codes

• 0 — success
• 1 — Redis connection failed or job ID not found
• 2 — invalid arguments or missing subcommand

Related

• nself queue — manage live queues (pause, drain, inspect)
• nself alerts — configure alerts when DLQ depth exceeds a threshold