---
title: 异常处理
---

工作流应用通常包含多个节点。如果因为某个节点的异常（例如 API 请求异常或 LLM 输出异常）而造成整个流程的运行失败，会迫使应用开发者不得不花费大量的精力排查故障并修复，这在复杂的工作流应用中尤为困难。

**异常处理机制**提供多样化的节点错误处理策略，能够在发生局部节点错误时抛出故障信息而不中断主流程。你可以设置出现异常时重新执行节点，或通过备用路径继续任务。为关键节点**添加异常处理机制将极大地增强应用整体的灵活性与稳健性。**

> 同时开启**错误重试**和**异常处理**功能时，将优先重试运行节点。若重试后仍然失败，再启用异常处理机制。

开发者无需在节点内编排复杂的逻辑代码或额外的节点应对错误情况。异常处理机制将简化工作流的设计复杂度，以多样的预设策略编排工作流的执行逻辑。

## 应用场景

**1. 网络异常处理**

示例：在某个工作流中需要通过三个 API 服务（例如天气服务、新闻摘要和社交媒体分析）获取数据并汇总。然而，其中一个服务因请求限制无法响应，导致数据获取失败。通过异常处理功能，主流程将继续处理其它两个成功的数据源，同时记录失败的 API 调用错误日志，供开发者稍后分析并优化服务调用策略。

**2. 工作流备用设计**

示例：某个 LLM 节点执行生成详细文档摘要任务，但因输入的篇幅过长而触发超出 Token 限制的异常。在节点中配置异常错误机制后，出现此类错误时，可以使用备用路径中的代码节点协助将内容切分为多个小段并重新调用 LLM 节点，避免流程中断。

**3. 异常信息预定义**

示例：运行工作流时可能会遇到某个节点返回模糊的错误信息（例如简单的“调用失败”），难以快速定位问题。开发者可以通过异常处理机制内编写预定义报错信息，为后续的应用调试提供更加清晰、准确的错误信息。

## 异常处理机制

以下四个类型的节点新增异常处理机制，点击标题即可阅读详细文档：

* [LLM](../node/llm)
* [HTTP](../node/http-request)
* [代码](../node/code)
* [工具](../node/tools)

**异常重试**

部分异常可以通过重新运行节点解决，此时可以在节点内开启 **“异常重试”** 功能，设置尝试次数与重试间隔时间。

![](https://assets-docs.dify.ai/2024/12/18097e4c94b67a79150b967fc50f9f43.png)

如果尝试重试运行节点后依然报错，将按照异常处理机制中的预设策略运行接下来的流程。

**异常处理**

异常处理机制提供以下三种选项：

• **无**：不处理异常，直接抛出节点的报错信息并中断整体流程。

• **默认值**：允许开发者预定义异常信息。异常发生后，使用预定义的值替代原节点内置的异常输出信息。

• **异常分支**：发生异常后，执行预编排的异常分支

如需了解各个策略的说明和配置方法，请参考[预定义异常处理逻辑](predefined-nodes-failure-logic)。

![Error handling](https://assets-docs.dify.ai/2024/12/6e2655949889d4d162945d840d698649.png)

## 快速开始

### 场景：为工作流应用添加应对错误输出代码的处理机制

下文将以一个简单的示例应用，演示如何在工作流应用内增设异常处理机制，以备用分支应对节点异常。

![](https://assets-docs.dify.ai/2024/12/958326384d3b60a98246e9ff565c7ed3.png)

**应用逻辑**： LLM 节点根据输入的指令，生成正确或错误格式的 JSON 代码内容，然后通过 A 代码节点执行代码并输出结果。如果 A 代码节点接收到了错误格式的 JSON 内容，则按照预设的异常处理机制，执行备用路径而继续主流程。

<Steps>
  <Step title="创建 JSON 代码生成节点">
    新建 Workflow 应用，并添加 LLM 节点和代码节点。通过 Prompt 让 LLM 根据指令生成正确或错误格式的 JSON 内容，然后通过 A 代码节点验证。

    **LLM 节点内的 Prompt 参考：**

    ```text
    You are a teaching assistant. According to the user's requirements, you only output a correct or incorrect sample code in json format.
    ```

    **代码节点中的 JSON 验证代码：**

    ```python
    def main(json_str: str) -> dict:
        obj = json.loads(json_str)
        return {'result': obj}
    ```
  </Step>

  <Step title="为 A 代码节点添加异常处理机制">
    A 代码节点是验证 JSON 内容的节点，如果接收到的 JSON 内容格式错误，需要通过异常处理机制运行备用路径，让下一个 LLM 节点修复错误内容并重新验证 JSON 从而继续主流程。在 A 代码节点的"异常处理"选项卡中，选择"异常分支"并新建 LLM 节点。
  </Step>

  <Step title="修正 A 代码节点输出的异常内容">
    在新的 LLM 节点中，填写 Prompt 并通过变量引用 A 代码节点的异常输出内容，并进行修复。添加 B 代码节点对 JSON 内容进行二次验证。
  </Step>

  <Step title="结束">
    添加变量聚合节点，汇总正确和错误分支的处理结果并输出至结束节点内，完成整体流程。

    ![错误处理流程图](https://assets-docs.dify.ai/2024/12/059b5a814514cd9abe10f1f4077ed17f.png)
  </Step>
</Steps>

> Demo 应用 DSL 文件[下载地址](https://assets-docs.dify.ai/2024/12/087861aa20e06bb4f8a2bef7e7ae0522.yml)。

## 状态描述

状态指的是节点状态与流程状态。清晰的状态说明有助于开发者判断当前工作流应用的运行现状，协助进行问题排查，快速了解信息并做出对应决策。引入异常处理机制后，节点状态和流程存在以下状态：

### **节点状态**

*   **成功**

    节点正常执行，并正确输出信息。
*   **失败**

    未启用异常处理，节点执行失败，输出报错信息。
*   **异常**

    在异常处理机制中启用了**默认值**或**异常分支**选项。节点执行时遇到了错误，但启用异常机制应对错误。

### 工作流状态

*   **成功**

    流程中的所有节点正常执行，结束节点能够正确输出信息，状态被标记为 Success。
*   **失败**

    因出现节点异常，整体流程被中断，状态被标记为 Failed。
*   **局部成功**

    节点出现异常，但启用了异常处理机制，整体流程最终运行正常。状态将会被标记为 Partial success。

## 常见问题

### 1. 启用异常处理机制前后的区别是什么？

**没有错误处理机制时：**

* **节点错误中断流程**：当 LLM 调用失败、网络出现问题或工具出错时，整个工作流程会立即中断，应用开发者需要手动查找并修复错误后重新运行流程。
* **缺乏灵活性**：开发者无法对不同错误类型或节点定义特定的处理逻辑。例如，无法在错误发生时继续后续流程或选择替代路径。
* **手动添加冗余节点**：避免错误影响全局需要额外设计大量节点来捕获和处理错误，增加了工作流程的复杂性和开发成本。
* **日志信息有限**：错误日志通常简单或不足，无法快速诊断问题。

**启用异常处理机制后：**

* **流程不中断**：即使某个节点发生错误，工作流程可以根据用户定义的规则继续运行，减少因单点失败导致的全局影响。
* **灵活自定义错误处理**：应用开发者可以为每个节点指定错误处理策略，如继续流程、记录日志，或切换到替代路径。
* **简化工作流程设计**：通用错误处理器减少了用户手动设计冗余节点的需求，流程更清晰简洁。
* **详细错误日志支持**：提供错误信息的自定义编排机制，便于开发者快速排查问题和优化流程。

***

### 2. 如何调试替代路径的执行情况？

你可以通过工作流程的运行日志检查条件判断和路径选择情况。异常分支的运行路线以黄色高亮显示，帮助开发者验证替代路径是否按预期执行。

{/*
Contributing Section
DO NOT edit this section!
It will be automatically generated by the script.
*/}

---

[编辑此页面](https://github.com/langgenius/dify-docs/edit/main/zh-hans/guides/workflow/error-handling/readme.mdx) | [提交问题](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)

