WorkflowError
workflow.WorkflowError 是业务 workflow 和 runtime 使用的标准错误类。它会保留错误类型、节点名、metadata 和经过清洗的 cause，最终进入执行报告。
签名
参数
| 参数 | 类型 | 说明 |
|---|---|---|
options | WorkflowErrorOptions | 标准错误配置，包含错误类型、消息、节点名、cause 和 metadata。 |
WorkflowErrorOptions
| 字段 | 说明 |
|---|---|
type | 错误分类。必填。 |
message | 对用户和报告可见的错误信息。必填。 |
nodeName | 关联节点名。节点执行失败时 runtime 会补充。 |
cause | 原始错误。序列化时只保留安全字段。 |
metadata | 可调试的结构化信息。 |
WorkflowErrorType
| 类型 | 常见来源 | 说明 |
|---|---|---|
input_validation | 参数解析、输入节点、文件节点 | 输入无效或配置缺失。 |
execution_aborted | abort signal、timeout、执行限制 | 执行被中断。 |
node_execution | 普通节点执行失败 | 普通节点抛出的未知错误。 |
provider_call | LLM provider 解析或调用 | provider 缺失、绑定错误或调用失败。 |
workflow_execution | workflow run 失败 | workflow 主流程失败。 |
stream_interrupted | 流式节点或 provider stream | 流式输出中断或失败。 |
实例字段
| 字段 | 类型 | 说明 |
|---|---|---|
name | "WorkflowError" | Error 名称。 |
message | string | 错误消息。 |
type | WorkflowErrorType | 错误分类。 |
nodeName | string | undefined | 关联节点。 |
metadata | object | undefined | 附加调试信息。 |
safeCause | WorkflowErrorCause | undefined | 清洗后的 cause。 |
序列化结构
| 字段 | 类型 | 说明 |
|---|---|---|
type | WorkflowErrorType | 错误分类。 |
message | string | 错误信息。 |
nodeName | string | undefined | 关联节点。 |
metadata | object | undefined | 附加信息。 |
cause | WorkflowErrorCause | undefined | 只保留安全 cause 字段。 |
错误码映射
运行报告会把失败类型映射成 payloaderrCode。
| 错误类型 | errCode |
|---|---|
input_validation | 400 |
execution_aborted | 499 |
stream_interrupted | 499 |
provider_call | 502 |
node_execution | 500 |
workflow_execution | 500 |
示例
何时使用
| 场景 | 建议 |
|---|---|
| 用户输入不合法 | 抛 input_validation。 |
| 外部服务调用失败 | 抛 provider_call 或让 provider 层包装。 |
| 想让报告保留结构化上下文 | 使用 metadata。 |
| 普通未知异常 | 可以直接抛，runtime 会包装为 WorkflowError。 |