[Bug]: Dataflow pipeline crashes with KeyError: ‘path’ when stored DSL lacks the path key

问题场景

用户在 RAGFlow 中创建了数据管道（dataflow agent，category=dataflow_canvas），之前运行正常。某次画布编辑器自动保存（发生在后端重连后）导致存储的 DSL 丢失了 path 键。此后无论是从画布编辑器点击“Test Run”，还是解析引用了该管道作为解析方法的知识库文档，任务都会在 0 秒内立即失败，且日志中没有任何组件执行痕迹。

报错原文

[ERROR][Exception]: 'path'

Task has been received.
[ERROR][Exception]: 'path'

File "agent/canvas.py", line 111, in load
    self.path = self.dsl["path"]
KeyError: 'path'

原因分析

根本原因在 agent/canvas.py 的 Graph.load() 方法：它使用严格的方括号取值 self.path = self.dsl["path"]，而 path 实际上是运行时执行状态（记录已访问组件 id 的列表），并不属于画布作者编辑的图结构本身。

同一类中对该字段的处理方式已经表明它是非必需的后端行为字段：

• Graph.__init__ 默认值为 self.path = []
• rag/flow/pipeline.py 中 Pipeline.run() 首次使用时自行初始化：if not self.path: self.path.append("File")
• 同类字段 memory 已用防御性读取：self.memory = self.dsl.get("memory", [])

因此，从未执行过的 DSL，或经过不保留该后端字段的代码路径重新保存后的 DSL，合法地没有 "path" 键。Issue 中通过直接查看 user_canvas 表确认了受影响画布存储的 DSL 顶层键为 ["components", "globals", "graph", "messages", "variables"]，完全没有 path 键。

环境排查

• 确认 RAGFlow 镜像版本是否为 v0.27.0 或包含相同 agent/canvas.py 代码的版本
• 检查部署方式是否为 Docker Compose 且使用 ragflow-cpu profile（Issue 中确认的环境；不排除其他部署方式同样受影响）
• 在数据库中检查出问题的画布 DSL：SELECT dsl FROM user_canvas WHERE id = '<画布_id>';，确认顶层 JSON 键中是否有 path
• 若需要复现，可在 MySQL 中执行：UPDATE user_canvas SET dsl = JSON_REMOVE(dsl, '$.path') WHERE id = '<id>';

解决步骤

1. 确认问题范围：检查出现报错的画布 ID，查看 user_canvas 表中该画布的 dsl 字段是否缺少 path 键。
2. 临时绕过（不修改源码）：手动为 DSL 补上 path 键，例如执行 MySQL 更新，将 DSL 中 path 设为空数组。注意这只是临时方案，下次画布自动保存仍可能再次丢失该键。
3. 正式修复（需要修改源码）：编辑 agent/canvas.py 中 Graph.load() 方法，将 self.path = self.dsl["path"] 改为 self.path = self.dsl.get("path", [])，与同类的 memory 字段保持一致的防御性读取方式。
4. 重新构建或重启 RAGFlow 服务使源码修改生效。
5. 如有能力，可向上游仓库提交 PR（该一行的修复与现有代码风格完全一致，应易于被接受合并）。

验证方法

修复后，对该画布重新执行“Test Run”，以及触发引用该管道作为解析方法的知识库文档解析。确认任务不再立即失败，日志中出现正常的组件执行记录（如“File fetched.”），且 [ERROR][Exception]: 'path' 不再出现。

参考来源

infiniflow/ragflow #18746

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。