iii-dead-letter-queues

name	iii-dead-letter-queues
description	Inspects and redrives jobs that exhausted all retries. Use when handling failed queue jobs, debugging processing errors, or implementing retry strategies.

Dead Letter Queues

Comparable to: SQS DLQ, RabbitMQ dead-letter exchanges

Key Concepts

Use the concepts below when they fit the task. Not every queue failure needs manual DLQ intervention.

• Jobs move to a DLQ after exhausting max_retries with exponential backoff (backoff_ms * 2^attempt)
• Each DLQ entry preserves the original payload, last error, timestamp, and job metadata
• Redrive via the built-in iii::queue::redrive function or the iii trigger CLI command
• Redriving resets attempt counters to zero, giving jobs a fresh retry cycle
• Always investigate and deploy fixes before redriving — blindly redriving repeats failures
• DLQ support available on Builtin and RabbitMQ adapters

Architecture

A queue consumer fails processing a job. The engine retries with exponential backoff up to max_retries. Once exhausted, the message moves to the DLQ. An operator inspects the failure, deploys a fix, then redrives the DLQ to replay all failed jobs.

iii Primitives Used

Primitive	Purpose
trigger({ function_id: 'iii::queue::redrive', payload: { queue } })	Redrive all DLQ jobs for a named queue
trigger({ function_id: 'iii::queue::status', payload: { queue } })	Check queue and DLQ status
iii trigger --function-id='iii::queue::redrive' --payload='{"queue":"name"}'