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
| Status | What it means |
|---|---|
PENDING | Just landed, awaiting triage |
INVESTIGATING | Someone is actively looking at it |
RESOLVED | The underlying issue is fixed; the entry stays for audit |
DISCARDED | Manually dropped; no further action |
What to do
- Open the DLQ entry from the schedule's detail page or from
/scheduler/dlq(workspace-admin view). - Read the failure reason and last error. Most failures fall into a few buckets — see 06-troubleshooting.md.
- Decide:
- Requeue — fixes were applied; fire a fresh execution from this entry. Creates a new
JobExecutionand 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.