Cascades
Docs
Execution states (canonical contract)

Execution states (canonical contract)

Terminal execution semantics for workflow runs and tasks — QUEUED, RUNNING, SUCCEEDED, FAILED, SKIPPED, TIMEOUT, and CANCELLED.

Cascades persists Prisma enums (WorkflowRunStatus, TaskRunStatus). Public HTTP contracts and integrations should use the canonical state names below for stable docs and clients.

Workflow run (canonical)

CanonicalPersisted mapping
QUEUEDPENDING (awaiting worker / executor handoff)
RUNNINGRUNNING
SUCCEEDEDSUCCESS
FAILEDFAILED (no task timeout detected)
TIMEOUTDerived when any failed task error matches a timeout pattern (e.g. [TIMEOUT], timeout after …)
CANCELLEDCANCELLED

Every run should end in a terminal canonical state (SUCCEEDED, FAILED, TIMEOUT, or CANCELLED). If the executor crashes mid-run, it finalizes the row to FAILED and fails open tasks so nothing stays stuck in RUNNING indefinitely.

Task run (canonical)

CanonicalPersisted mapping
QUEUEDPENDING or QUEUED
RUNNINGRUNNING
RETRYINGRETRYING
SUCCEEDEDSUCCESS
FAILEDFAILED (non-timeout)
SKIPPEDSKIPPED
TIMEOUTFAILED where error indicates executor timeout
CANCELLEDCANCELLED

Task timeouts use the executor’s withTimeout guard; timeout failures are labeled in the stored error field so callers can surface TIMEOUT without a DB migration.

API surfaces

  • Experimental proof summary: GET /api/workflows/{id}/proof — returns canonicalWorkflowState and per-task canonical states (see OpenAPI Proof APIs under /openapi.json).
  • Run submission: POST /api/workflows/run — may return 503 when ENV_TIER is staging or production and the BullMQ worker path is not configured.

Related

CommunityReport issue / Discuss(tags: Cascades, workflows)
DAG ExecutionRetries & Timeouts