[Refactor/Chore] Migrate failed-run reasons to structured error types
- Dominant language
- TypeScript
- Stars
- 156k
- Forks
- 24.6k
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 610
Description
### Self Checks
- [x] I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542).
- [x] This is only for refactors or chores; if you would like to ask a question, please head to [Discussions](https://github.com/langgenius/dify/discussions/categories/general).
- [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones.
- [x] I confirm that I am using English to submit this report, otherwise it will be closed.
- [x] 【中文用户 & Non English User】请使用英语提交,否则会被关闭 :)
- [x] Please do not modify this template :) and fill in all the required fields.
### Description
Follow-up to #40116.
#### Problem
Dify Agent failed-run `reason` values are produced by several unrelated exception and lifecycle paths. They currently mix Dify-owned categories, exception names, provider-defined strings, and other diagnostic details. Agent App and Workflow consumers interpret some of these values independently, so it is unclear which values form a stable public contract.
#40116 introduces `RunFailureType` as a structured, machine-readable failure classification, but the existing failed-run `reason` field remains alongside it and can continue accumulating ad hoc values.
#### Goal
Inventory the existing failed-run `reason` values and their consumers, select the meaningful and stable categories that belong in `RunFailureType`, and migrate those classifications to the enum. Once the relevant producers and consumers have moved to structured error types, remove the scattered failed-run `reason` contract and its downstream fallbacks while preserving readable diagnostic errors.
### Motivation
A single structured error type contract gives consumers predictable values and prevents implementation-specific strings from silently becoming frontend or Workflow error types.
### Additional Context
This issue concerns the `reason` attached to failed runs and propagated through the Agent backend failure chain. Cancellation reasons, HITL pause reasons, validation explanations, and unrelated fields with the same name are not part of this cleanup.
Contributor guide
Research direction
Start by inventorying failed-run reason producers and consumers across the Agent backend failure chain, including Agent App and Workflow consumers. Compare those values with the RunFailureType introduced in #40116, then define the stable classifications to migrate and verify that the reason contract and downstream fallbacks are removed while readable diagnostic errors remain.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, typescript
- Domain
- api, backend
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100