Skip to main content

Dead Letter Queue (DLQ)

When an execution fails and every retry attempt also fails, the execution lands in the dead-letter queue. The DLQ is your workspace's parking lot for failed runs that need human attention.

When a job lands in the DLQ​

A scheduled job's retryPolicy controls retries. Once the count is exhausted (or a non-retryable error short-circuits) the engine emits a DLQ entry containing:

  • The original execution id (originalRunId)
  • The schedule id and name
  • The full failure reason and last error message + stack
  • Timestamp of first attempt and last attempt
  • The exact executor configuration that was used

DLQ entries are never silently retried. They sit in PENDING status until you act.

Statuses​

StatusWhat it means
PENDINGJust landed, awaiting triage
INVESTIGATINGSomeone is actively looking at it
RESOLVEDThe underlying issue is fixed; the entry stays for audit
DISCARDEDManually dropped; no further action

What to do​

  1. Open the DLQ entry from the schedule's detail page or from /scheduler/dlq (workspace-admin view).
  2. Read the failure reason and last error. Most failures fall into a few buckets — see 06-troubleshooting.md.
  3. Decide:
  • Requeue — fixes were applied; fire a fresh execution from this entry. Creates a new JobExecution and clears the entry.
  • Discard — the run is no longer relevant (stale data, retired job). Records the reason for the audit trail.

Permissions​

DLQ actions require schedule-dlq:execute (requeue) or schedule-dlq:delete (discard). Read access requires schedule-dlq:read.

Auditing​

Every DLQ action emits an audit-log event with the actor id, the entry id, the action taken, and (for discards) the reason text. Find these in the workspace audit log under module scheduler.