遇到 n8n 校验错误/警告时如何解读并修复（含误报识别与自…

当 validate_node 或 validate_workflow 返回错误、警告或疑似误报时，用来判断哪些必须修、哪些可忽略、如何迭代修复并跑通工作流。

适用场景

解决思路

1. 把校验当作迭代过程：预期 2-3 轮 validate → fix 循环（平均 23 秒思考错误、58 秒修复），不要指望一次通过。
2. 先看返回结果的 valid 字段：true 表示配置有效，false 表示存在必须先修复的错误。
3. 优先修复 errors：每条错误都带 property、message、fix，必须逐条解决。
4. 按错误类型对症处理：missing_required 用 get_node 查必填字段后补上；invalid_value 对照错误里的允许列表或 get_node（枚举区分大小写）；type_mismatch 转换成期望类型（如字符串 "100" 改为数字 100）；invalid_expression 检查 {{}} 与拼写（参考 n8n Expression Syntax）；invalid_reference 修正节点名或执行 cleanStaleConnections。
5. 遇到 patchNodeField 错误（find-not-found、ambiguous match、invalid/unsafe regex）时，按严格模式处理，不要让它静默继续。
6. 再审查 warnings：每条带 message 和 suggestion，逐条判断是否处理；security 和 deprecated 警告在所有 profile 下都会出现，应视为真实问题。
7. 最后考虑 suggestions（optimization、alternative），属于可选优化，非必需。
8. 选择校验 profile：minimal 用于快速结构检查（跳过枚举校验和所有建议）；runtime 作为日常默认（错误 + 安全/弃用警告，无最佳实践建议）；ai-friendly 在 runtime 基础上加最佳实践建议；strict 在 ai-friendly 基础上加残留属性检查，用于生产加固。注意四个 profile 是累积的，ai-friendly 比 runtime 更严格。
9. 信任自动净化（auto-sanitization）：任何工作流保存时都会自动规范化二元运算符（移除多余的 singleValue）、一元运算符（补 singleValue: true）以及 IF/Switch 的 conditions.options 元数据，不要手动修这些形状。
10. 自动净化无法处理的情况手动解决：指向不存在节点的连接用 cleanStaleConnections；分支数不匹配则增删连接或规则；悖论性损坏状态可能需要手动介入数据库。
11. 识别已知误报（n8n-mcp 2.85.0，升级后需复查）：fan-out 中目标是 Respond to Webhook/Send Email 或名字含 error/fail/catch/exception 的节点时报的 "Incorrect error output configuration" 错误，仅在消息文本完全匹配且已检查 connections 确认该节点在成功路径上时忽略，并在回复中说明忽略 n8n-mcp#1111 及原因，且不要用默认 fix types 运行 n8n_autofix_workflow（排除 error-output-config）。
12. 忽略字符串内 json/items 上的 "Possible missing $ prefix" 警告（如 $jmespath($('X').all(), "[?json.country=='PL'].json.name") 中 json. 前缀是必需的）。
13. 对 language: "pythonNative" 的 Code 节点，validate_node 报 "Code cannot be empty" (jsCode) 是误报，改为校验整个工作流。
14. 忽略 Python 单字典返回在 all-items 模式下报的 "Return value must be a list of dicts"，n8n 接受并输出一个 item。
15. 注意校验盲区：$jmespath 的语法/引号错误、{{ }} 内任何 JS 错误（解析为 null 但执行仍为绿色）、原生 Python 的 _input/_json、点访问、被禁导入和类等；校验通过加运行成功仍不等于正确，必须检查输出值。
16. 对最佳实践建议按场景判断是否修："without error handling" 在开发/测试和非关键通知可接受，生产处理重要数据要修；"No retry logic" 对幂等操作、自带重试的 API、手动触发可接受，对易抖动外部服务和生产自动化要修；"rate limits and transient failures" 对内部/低量/服务端限流的 API 可接受，对公开高量 API 要修；"Unbounded query" 对小规模已知数据集、聚合、开发测试可接受，对生产大表查询要修。
17. 用 validate_workflow 校验整个工作流（节点配置、连接、表达式、流程结构），按需开启 validateNodes、validateConnections、validateExpressions 并指定 profile。
18. 处理常见工作流错误：连接指向不存在节点则删除陈旧连接或创建缺失节点；出现环是警告而非硬错误（运行时可控循环如错误重试、数据驱动分页、路由回环是合法的），仅在非预期时确保有真实出口（条件节点、错误输出或有界计数器）；多个触发节点则删除多余触发器或拆分为独立工作流；节点未连接则连接或删除。
19. 按恢复策略处理：配置严重损坏时从 get_node 取必填字段，重建最小可用配置再逐步加功能并每次校验；工作流校验通过但执行错误时用二分法删一半节点定位问题；出现 "Node not found" 时用 n8n_update_partial_workflow 执行 cleanStaleConnections；可自动修复的错误用 n8n_autofix_workflow。
20. 使用 n8n_autofix_workflow 时先预览（applyFixes: false，confidenceThreshold 默认 medium），审查后再应用；可修复类型包括 expression-format、typeversion-correction、error-output-config、node-type-correction、webhook-missing-path、typeversion-upgrade、version-migration；置信度 high（90%+ 可安全自动应用）、medium（70-89% 建议审查）、low（<70% 需人工审查）；可用 fixTypes 指定类型；版本升级后查看响应中的 postUpdateGuidance 获取迁移步骤。
21. 校验通过后必须实际运行一次：有 webhook/form/chat 触发器时用 n8n_test_workflow({workflowId})（默认 method: "auto" 检测触发器并发 HTTP，工作流需处于激活状态）。
22. 无外部触发器（Manual Trigger、Schedule、子工作流）时走 pin-data 路径：先 n8n_test_workflow({workflowId, method: "prepare"}) 列出需要固定数据的节点；再按节点名构造样本数据，每项包在 {json: {...}} 中（如 {"When clicking 'Test workflow'": [{"json": {"orderId": "1234", "email": "a@b.com"}}]}），注意不要用扁平对象；最后 n8n_test_workflow({workflowId, method: "pinned", pinData}) 运行并等待结果。
23. 快速手动运行可用 method: "direct"，它启动手动执行后立即返回，用 n8n_executions({action: "get", id: executionId, mode: "error"}) 轮询结果；direct 不固定任何数据，所有节点都会执行且外部调用是真实的；pinned 也只固定触发器、带凭证和 HTTP Request 节点；executionMode: "production" 只改变执行上下文而非副作用，除非用户要求否则保持默认。
24. 注意 method: "auto" 永远不会通过 n8n 的 MCP 服务器运行工作流；无外部触发器时它会报告并提示 prepare/pinned/direct，只有显式指定方法才会路由运行。
25. 首次路由运行前需征得同意：工作流 "Available in MCP" 关闭时返回 WORKFLOW_NOT_EXPOSED，带 exposeToMcp: true 重跑会打开该设置并重试一次；这是工作流上可见且持久的设置（且属于工作流更新，可能覆盖并发的 UI 编辑），传参前先询问用户；该流程只会启用设置，不会隐式关闭；如需关闭用 n8n_update_partial_workflow({id: workflowId, operations: [{type: "updateSettings", settings: {availableInMCP: false}}]}) 或 UI 开关。
26. 读取运行结果：已启动但失败会返回 EXECUTION_FAILED 和 executionId，用 n8n_executions({action: "get", id, mode: "error"}) 检查，从抛错的节点开始修，然后重新校验并运行。
27. 审查已有工作流（已通过 validate_workflow 但存在校验看不到的问题，如静默连接错误、易注入查询、丢 item 的 Switch、Set/Code 反模式、缺失错误路径）时，用 n8n_get_workflow 拉取工作流并对照 REVIEW_CHECKLIST.md 做分级审计（MUST FIX / SHOULD FIX / NICE TO HAVE），同时运行 n8n_audit_instance 发现硬编码密钥和未认证 webhook。
28. 遵循最佳实践：每次重大改动后校验；完整阅读错误消息；一次修一个错误迭代推进；部署前用 runtime profile；假设成功前先检查 valid 字段；运算符问题信任自动净化；不清楚要求时用 get_node；记录你接受的误报。
29. 避免这些做法：激活前跳过校验；试图一次修完所有错误；忽略错误消息；开发期用 strict profile（太吵）；假设校验已通过（始终检查结果）；手动修自动净化能处理的问题；带着未解决错误部署；忽略所有警告（有些很重要）。

适用边界 · 注意事项

• 需要先安装并运行 n8n-mcp（≥ 2.63.0，误报修复与 profile 累积行为依赖该版本）并具备 n8n 实例访问权限，纯手工编写 n8n 工作流时无法使用这些校验工具。
• 运行工作流测试（n8n_test_workflow 的 pinned/direct 路径）依赖 n8n 2.34+ 的 MCP 服务器与 N8N_MCP_ACCESS_TOKEN，且首次路由运行需用户同意开启 "Available in MCP"。
• 本技能针对 n8n 工作流的校验与修复，不适用于其他平台的流程编排或非 n8n 的 JSON schema 校验。