Skip to content

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