Skip to main content

Workflow Execution State Machine

This state diagram illustrates the lifecycle of a workflow execution (referred to as a "Run" or "Action" in the SDK) as it transitions through various phases defined by the ActionPhase enum.

The execution begins in the QUEUED state upon creation. It then progresses through resource allocation (WAITING_FOR_RESOURCES) and environment setup (INITIALIZING) before entering the RUNNING state where the actual user code executes.

Transitions to terminal states can occur from various points:

  • Success: The execution completes successfully from the RUNNING state.
  • Failure: An error occurs during execution or initialization.
  • Timeout: The execution exceeds its configured time limit.
  • Abort: A user manually terminates the execution via the abort() method, which is possible from any non-terminal state.

The SDK provides mechanisms like wait() and watch() to monitor these transitions in real-time, often displaying progress via a Rich Validation Reports interface. Terminal states are identified by the is_terminal property on the phase object.

Key Architectural Findings:

  • The primary state entity is the ActionPhase enum, which maps directly to Flyte's internal execution phases.
  • Execution states include QUEUED, WAITING_FOR_RESOURCES, INITIALIZING, RUNNING, SUCCEEDED, FAILED, ABORTED, and TIMED_OUT.
  • Terminal states are explicitly defined in the code via the ActionPhase.is_terminal property.
  • Transitions are primarily managed by the Flyte backend, but the SDK can trigger the ABORTED state through the abort() method on Run or Action objects.
  • The Run and Action classes in src/flyte/remote/ provide the interface for observing state changes using wait() and watch() methods.
Diagram unavailable

This diagram could not be rendered and has been omitted. It will be restored on the next regeneration.

Diagram source
stateDiagram-v2
    [*] --> QUEUED: Run Created

    state "Active Execution" as Active {
        QUEUED --> WAITING_FOR_RESOURCES: Backend Scheduling
        WAITING_FOR_RESOURCES --> INITIALIZING: Resource Allocation
        INITIALIZING --> RUNNING: Container Startup
    }

    state "Terminal States" as Terminal {
        RUNNING --> SUCCEEDED: Task Success
        RUNNING --> FAILED: Task Error
        RUNNING --> TIMED_OUT: Execution Timeout
        
        QUEUED --> ABORTED: Manual Abort
        WAITING_FOR_RESOURCES --> ABORTED: Manual Abort
        INITIALIZING --> ABORTED: Manual Abort
        RUNNING --> ABORTED: Manual Abort
    }

    SUCCEEDED --> [*]
    FAILED --> [*]
    ABORTED --> [*]
    TIMED_OUT --> [*]

    note right of Active
        Transitions in this block are 
        typically driven by the 
        Flyte backend scheduler.
    end note

    note left of Terminal
        Terminal states are final.
        ActionPhase.is_terminal 
        returns True for these.
    end note