agent can't parse prefect flow run states, parser failed

TL;DR

Prefect's state model has more states than agents expect: Scheduled, Pending, Running, plus Crashed, Cancelled, and Paused variants. Parse states against the full enum and classify terminal versus non-terminal explicitly. A parser with a hardcoded short list breaks on the first state it did not anticipate.

agent can't parse prefect flow run states, parser failed

Use this when

• An agent's parser fails on a Prefect flow run state.
• A new state appears that the parser did not know.
• Terminal versus non-terminal classification is wrong.

Not for this skill when

• The run is stuck in a state. That is a run problem.
• States parse but the agent misjudges them. That is logic, not parsing.

Steps

1. Capture the unparsable state value verbatim. Note the value. Verify: the gap is named
2. Read Prefect's state enum for the full list in your version. Note the complete set. Verify: the enum is on the table
3. Rewrite the parser to accept the full enum and classify terminal states explicitly. Note the new logic. Verify: the parser is complete
4. Add every state as a regression case. Note the tests. Verify: the enum is pinned
5. Verify against a live run history with varied states. Note the clean parse. Verify: the fix is verified

Variant phrasings

prefect flow run states list

The enum-shaped search.

prefect terminal states

The classification phrasing.

Compatibility: Prefect 2.x state model. New states can appear in minor versions; parse defensively.

Why it happens

Prefect models run lifecycle richly: the difference between Crashed and Failed matters, and Paused, Suspended, and Cancelling exist for real workflows. Agents written against a mental model of pending, running, done break on the richer reality. Worse, misclassifying a non-terminal state as terminal makes the agent stop watching a run that is still alive. Parsing the full enum and classifying explicitly turns the state model from a trap into a tool.

Edge cases / pitfalls

• Prefect 2.x added states across minor versions. A parser pinned to one version's enum rots; fetch or vendor the current enum.
• State names are strings in the API. Compare case-sensitively against the enum; do not lowercase and hope.
• Subflow and task runs share the state model but transition differently. The same parser works; the expectations differ.
• A state the parser has never seen should raise loudly, not default to something. Unknown is a bug signal.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_j53ZoUFPn2ThosqpX6NIOA