State

State 表示一次 flow run 或 task run 当前所处的状态。

它不是简单的字符串，而是一个包含状态信息的对象，可以帮助你判断：

当前是否在运行
是否成功结束
是否失败 / 崩溃 / 被取消
是否命中缓存
是否正在等待重试

只有 run 才有 state，flow / task 本身没有 state。

状态类型

Prefect 的 State 有两个维度：

Name（名称）：更偏展示（UI、日志）
Type（类型）：驱动底层编排逻辑

Name	Type	Terminal?	说明
`Scheduled`	`SCHEDULED`	❌	已调度，将在未来某个时间运行
`Late`	`SCHEDULED`	❌	已过调度时间，但还没被 worker 执行（可能有问题）
`AwaitingRetry`	`SCHEDULED`	❌	运行失败，但还有重试次数，等待重试
`AwaitingConcurrencySlot`	`SCHEDULED`	❌	等待可用并发资源（被并发限制卡住）
`Resuming`	`SCHEDULED`	❌	准备恢复执行（从暂停状态恢复）
`Pending`	`PENDING`	❌	已提交执行，但还在等待资源或前置条件
`Running`	`RUNNING`	❌	正在执行
`Retrying`	`RUNNING`	❌	正在执行（重试中的运行）
`Paused`	`PAUSED`	❌	暂停执行，等待人工或条件触发继续
`Suspended`	`PAUSED`	❌	暂停且进程已退出（比 paused 更彻底）
`Cancelling`	`CANCELLING`	❌	正在清理资源，准备取消
`Cancelled`	`CANCELLED`	✅	被用户取消
`Completed`	`COMPLETED`	✅	成功执行完成
`Cached`	`COMPLETED`	✅	使用缓存结果（没有真正执行）
`RolledBack`	`COMPLETED`	✅	执行成功，但事务回滚了
`Failed`	`FAILED`	✅	代码执行失败（异常且无重试）
`TimedOut`	`FAILED`	✅	超时导致失败
`Crashed`	`CRASHED`	✅	基础设施问题（不是代码错误）

状态流转

%%{
  init: {
    'theme': 'neutral',
    'flowchart': {
      'curve' : 'basis',
      'rankSpacing': 80,
      'nodeSpacing': 70,
      'width': 5
    }
  }
}%%

flowchart TD
    %% Style definitions
    classDef scheduled fill:#fcd14edb,stroke:#fcd14edb
    classDef pending fill:#A99FADdb,stroke:#A99FAD
    classDef running fill:#1860f2db,stroke:#1860f2db
    classDef paused fill:#a99faddb,stroke:#a99faddb
    classDef completed fill:#2ac769db,stroke:#2ac769db,stroke-width:2px
    classDef failed fill:#fb4e4ef5,stroke:#fb4e4ef5,stroke-width:2px
    classDef crashed fill:#f97316db,stroke:#f97316db,stroke-width:2px
    classDef cancelled fill:#3d3d3da8,stroke:#3d3d3da8,stroke-width:2px
    classDef awaiting_concurrency_slot fill:#ede7f6,stroke:#4527a0,stroke-width:2px

    %% States
    subgraph scheduled_type[Scheduled]
    Scheduled[Scheduled]:::scheduled
    Late[Late]:::scheduled
    AwaitingConcurrencySlot[AwaitingConcurrencySlot]:::scheduled
    end

    Running[Running]:::running

    Failed[Failed]:::failed

    subgraph scheduled_type2[Scheduled]
    AwaitingRetry[Awaiting Retry]:::scheduled
    end

    subgraph running_type[Running]
    Retrying[Retrying]:::running
    end

    Pending[Pending]:::pending



    Cancelling[Cancelling]:::cancelled
    Cancelled[Cancelled]:::cancelled

    Cached[Cached]:::completed
    RolledBack[Rolled Back]:::completed
    Crashed[Crashed]:::crashed

    Paused[Paused]:::paused

    Completed[Completed]:::completed

    %% Connections
    Scheduled --> |Scheduled start time passes without entering Pending| Late
    Scheduled --> |Worker/Runner successfully submits run| Pending
    Scheduled --> |Worker encounters concurrency limit| AwaitingConcurrencySlot

    AwaitingConcurrencySlot --> Pending

    Late -->  Pending

    Pending --> |Preconditions met| Running    


    Running -.-> |Success| Completed

    %%problematic section:
    Retrying -.-> |Success| Completed
    Failed --> |Retries remaining| AwaitingRetry
    AwaitingRetry --> |Retry attempt| Retrying
    Retrying -.-> |Failure| Failed



    Running -.-> |Error| Failed

    Running -.-> |Infrastructure issue| Crashed
    Running -.-> |Cache hit| Cached
    Running -.-> |Transaction rollback| RolledBack
    Running --> |User cancels| Cancelling

    Running --> |Manual pause| Paused
    Paused --> |Resume| Running

    Cancelling -.-> |Cleanup complete| Cancelled