n8n-validation-expert

n8n 验证专家

解读和修复 n8n 验证错误的专家指南。

---

验证理念

尽早验证，频繁验证

验证通常是迭代进行的：

• 预期会有验证反馈循环
• 通常需要 2-3 轮「验证 → 修复」
• 平均需要 23s 思考错误、58s 修复错误

关键见解：验证是一个迭代过程，而不是一次性操作！

---

错误严重级别

1. 错误（必须修复）

会阻止工作流执行——必须在激活前解决

类型：

• missing_required - 未提供必填字段
• invalid_value - 值与允许的选项不匹配
• type_mismatch - 数据类型错误（例如使用字符串而非数字）
• invalid_reference - 引用的节点不存在
• invalid_expression - 表达式语法错误

示例：

{
  "type": "missing_required",
  "property": "channel",
  "message": "Channel name is required",
  "fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)"
}

2. 警告（应该修复）

不会阻止执行——工作流可以激活，但可能存在问题

类型：

• best_practice - 建议遵循，但并非必需——仅在 ai-friendly / strict 下显示
• deprecated - 正在使用旧版 API/功能——在所有配置文件下显示
• security - 硬编码机密信息、未经身份验证的 Webhook——在所有配置文件下显示
• performance - 潜在的性能问题——仅供参考，在 ai-friendly / strict 下显示

示例（最佳实践——在 ai-friendly / strict 下显示）：

{
  "type": "warning",
  "nodeName": "Slack",
  "message": "Slack API can have rate limits and transient failures"
}

3. 建议（可选）

锦上添花——有助于改进工作流的优化项

类型：

• optimization - 可以更高效
• alternative - 有更好的方式实现相同结果

---

验证循环

遥测数据中的模式

7,841 次出现这种模式：

1. Configure node
   ↓
2. validate_node (23 seconds thinking about errors)
   ↓
3. Read error messages carefully
   ↓
4. Fix errors
   ↓
5. validate_node again (58 seconds fixing)
   ↓
6. Repeat until valid (usually 2-3 iterations)

示例

// Iteration 1
let config = {
  resource: "channel",
  operation: "create"
};

const result1 = validate_node({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Error: Missing "name"

// ⏱️  23 seconds thinking...

// Iteration 2
config.name = "general";

const result2 = validate_node({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Error: Missing "text"

// ⏱️  58 seconds fixing...

// Iteration 3
config.text = "Hello!";

const result3 = validate_node({
  nodeType: "nodes-base.slack",
  config,
  profile: "runtime"
});
// → Valid! ✅

这很正常！ 不要因为需要多次迭代而气馁。

---

验证配置文件

四种配置文件是累积的（n8n-mcp ≥ 2.63.0）：每种配置文件都会显示较低级别配置文件显示的所有内容，以及更多内容。分界点在于最佳实践提示——minimal 和 runtime 不显示这些提示；ai-friendly 和 strict 则会显示。除 minimal 会跳过少数配置级检查（例如对明确指定的 operation 进行枚举验证）外，所有配置文件中的错误都相同。所有配置文件都会显示安全性和弃用警告。

minimal

适用场景：搭建工作流时进行快速结构检查。

显示内容：会阻止执行的硬性错误（缺少必填字段、代码为空、连接断开）。跳过枚举检查和所有提示。

速度最快，限制最少。

runtime（推荐的默认配置）

适用场景：构建过程中持续进行验证；适合日常使用的配置文件。

显示内容：错误（必填字段、值类型、允许的值、依赖项、无效引用），以及安全性和弃用警告。不显示最佳实践提示。

均衡之选——捕获所有会造成问题的情况，同时不对代码风格提出意见。

ai-friendly

适用场景：希望在部署前获得最佳实践建议。

显示内容：runtime 的所有内容，以及最佳实践提示——针对每个节点给出的「未启用错误处理」建议、「Webhook 应始终发送响应」提示、速率限制说明、typeVersion 过时建议、cachedResultName 和长链提示。

注意：ai-friendly 比 runtime 更严格，而非更宽松。（旧版文档称它可以减少误报——只有在配置文件筛选功能失效时，这一点才成立；现在已经修复。）

strict

适用场景：强化对生产环境至关重要的工作流。

显示内容：ai-friendly 的所有内容，以及未使用属性检查（「属性 ‘X’ 将不会使用——在当前设置下不可见」）。

最严格的静态检查。 误报已从源头修复，因此这些警告是值得权衡的建议，而非需要对抗的噪声。

常见错误类型

五种核心错误类型，按大致出现频率排序：

• missing_required —— 未提供必填字段。使用 get_node 查看必填字段，然后补上。
• invalid_value —— 值与允许的选项不匹配（枚举区分大小写）。检查错误中列出的允许值，或使用 get_node。
• type_mismatch —— 数据类型错误（字符串 "100" 与数字 100 不同）。转换为预期类型。
• invalid_expression —— 表达式语法错误（缺少 {{}}、拼写错误）。请参阅 n8n Expression Syntax 技能。
• invalid_reference —— 引用的节点不存在（已重命名、已删除或拼写错误）。修正名称，或使用 cleanStaleConnections。

第六类是 patchNodeField 错误（未找到、匹配不明确、正则表达式无效/不安全），当 patchNodeField 操作在 n8n_update_partial_workflow 期间失败时会出现——这是有意采用的严格行为，会报错而不是静默继续。

上述每种类型都有可运行示例（错误配置 → 修复），此外还有 patchNodeField 错误案例及其修复方法，详见 ERROR_CATALOG.md。

---

自动净化系统

自动规范化常见的运算符结构，适用于 ANY 工作流更新——n8n_create_workflow、n8n_update_partial_workflow 或任何保存操作。请信任它；不要手动修复这些问题。

保存时会规范化的内容：

• 二元运算符（equals、notEquals、contains、notContains、greaterThan、lessThan、startsWith、endsWith）——移除多余的 singleValue 属性。
• 一元运算符（isEmpty、isNotEmpty、true、false）——添加 singleValue: true。
• IF/Switch 元数据——补全 IF v2.2+ 和 Switch v3.2+ 的 conditions.options。

验证不再因这些结构而报错（n8n-mcp ≥ 2.63.0）。n8n 会根据运算符名称推断是否为一元运算符，并为 conditions.options 子字段设置默认值，因此，无论是否存在 singleValue 和选项元数据，validate_node / validate_workflow 都会接受该条件——净化器只会在保存时将其整理为规范形式。（旧版服务会对未经规范化的结构错误地报错；如果遇到这种情况，请升级。）仍然属于真实错误的情况：v2 节点使用 v1 结构的 conditions 对象、没有任何条件的空筛选器，以及 v2 结构中使用旧版 v1 运算符名称（例如 smaller）。

净化器无法修复的内容（需手动处理）：连接到不存在节点的无效连接（使用 cleanStaleConnections）、分支数量不匹配（添加/删除连接或规则），以及自相矛盾的损坏状态（可能需要手动干预数据库）。

修复前后的示例及无法修复事项的完整说明，详见 ERROR_CATALOG.md（Auto-Sanitization 部分）。

---

误报

验证器全面升级（n8n-mcp ≥ 2.63.0）后，已消除经典误报——表达式中的模板字面量、可选链、操作省略时的默认值、Webhook → Respond-to-Webhook 模式、IF/Filter 旧版结构等，都不再触发。

已知例外（n8n-mcp 2.85.0，已向上游报告；升级后请重新检查）：

• ERROR "Incorrect error output configuration… appear to be error handlers but are in main[0]"：在扇出连接中，如果某个目标节点是 Respond to Webhook 或 Send Email，或者其名称中包含 error / fail / catch / exception，就可能出现此错误。按照建议将 Respond to Webhook 移到 main[1]，意味着只有上游节点失败时，Webhook 才会响应。仅当消息与此文本完全匹配，并且你已检查 connections、确认该命名节点按设计位于成功路径上时，才将其视为误报。在这种情况下，保留原有连线，在回复中说明你忽略了 n8n-mcp#1111 及原因，不要使用默认修复类型运行 n8n_autofix_workflow（排除 error-output-config，否则可能会重接成功路径）。其他所有 valid: false 错误都仍需修复。(n8n-mcp#1111)
• Warning "Possible missing $ prefix"：在字符串中的 json/items 上出现，例如 $jmespath($('X').all(), "[?json.country=='PL'].json.name")。此处需要 json. 前缀，因此可忽略该警告。(#1115)
• 对 language: "pythonNative" 的 Code 节点运行 validate_node → "Code cannot be empty" (jsCode)。这是误报；请改为验证工作流。(#1112)
• Python "Return value must be a list of dicts"：在处理所有项目的模式下返回单个字典时出现。n8n 接受这种返回值，并会输出一个项目。(#1113)

**盲点（工作流有效，但运行时结果错误）：**表达式中的 $jmespath 语法或引号错误（#1114）；{{ }} 中的任何 JS 错误，都会解析为 null，但执行仍显示成功（参见 n8n-expression-syntax）；原生 Python 中的错误，例如旧式 _input/_json、点号访问、被阻止的导入和类（#1113，参见 n8n-code-python）。验证通过且运行成功仍不能证明一切正确：请检查输出值。

剩下的是最佳实践建议（仅在 ai-friendly / strict 配置下显示），它们指出了真实的权衡，但在你的场景中可能可以接受。并非每条建议都需要修复——很多取决于具体情况。以下是常见建议，以及何时可以接受、何时值得修复：

• "...without error handling"——适用于开发/测试和非关键通知；处理重要数据的生产环境则应修复。（这绝不会是硬性错误——样式不会阻止执行。）
• "No retry logic"——适用于幂等操作、自带重试机制的 API、手动触发；不稳定的外部服务和生产自动化则应修复。
• "...rate limits and transient failures"——适用于内部、低流量或受服务端限制的 API；公共、高流量 API 则应修复。
• "Unbounded query"——适用于规模较小且已知的数据集、聚合、开发/测试；针对大型表的生产查询则应修复。

相比之下，安全和弃用警告会在所有配置下显示，应当视为真实问题。

各个情况的完整指南、验证器不再标记的问题清单、配置策略、“是否应该修复？”决策框架，以及如何记录已接受的建议，请参阅 FALSE_POSITIVES.md。

---

验证结果结构

完整响应

{
  "valid": false,
  "errors": [
    {
      "type": "missing_required",
      "property": "channel",
      "message": "Channel name is required",
      "fix": "Provide a channel name (lowercase, no spaces)"
    }
  ],
  "warnings": [
    {
      "type": "best_practice",
      "property": "errorHandling",
      "message": "Slack API can have rate limits",
      "suggestion": "Add onError: 'continueRegularOutput'"
    }
  ],
  "suggestions": [
    {
      "type": "optimization",
      "message": "Consider using batch operations for multiple messages"
    }
  ],
  "summary": {
    "hasErrors": true,
    "errorCount": 1,
    "warningCount": 1,
    "suggestionCount": 1
  }
}

如何阅读结果

1. 先检查 valid — true 表示配置有效；false 表示部署前必须先修复错误。
2. 先修复 errors — 每项都包含 property、message 和 fix。必须解决这些问题。
3. 查看 warnings — 每项都包含 message 和 suggestion；根据具体情况决定是否处理（参见上文“误报”）。
4. 考虑 suggestions — 可选的改进建议，并非必需。

---

工作流验证

validate_workflow（结构）

验证整个工作流，而不仅是单个节点

检查项：

1. 节点配置 - 验证每个节点
2. 连接 - 检查是否存在无效引用
3. 表达式 - 检查语法和引用是否有效
4. 流程 - 检查工作流结构是否合理

示例：

validate_workflow({
  workflow: {
    nodes: [...],
    connections: {...}
  },
  options: {
    validateNodes: true,
    validateConnections: true,
    validateExpressions: true,
    profile: "runtime"
  }
})

常见工作流错误

1. 连接断开

{
  "error": "Connection from 'Transform' to 'NonExistent' - target node not found"
}

修复方法：删除过时的连接，或创建缺失的节点

2. 循环（警告，而非错误）

{
  "warning": "Workflow contains a cycle: Node A → Node B → Node A"
}

循环是警告，而非严重错误（n8n-mcp ≥ 2.63.0）——由运行时控制的循环（错误重试、数据驱动的分页、路由器反馈等）会执行至完成，属于合理用法。仅在循环非预期时才修复：确保循环有实际的退出条件（条件节点、错误输出或有界计数器），避免无限循环。

3. 多个起始节点

{
  "warning": "Multiple trigger nodes found - only one will execute"
}

修复方法：移除多余的触发器，或拆分为多个独立工作流

4. 未连接的节点

{
  "warning": "Node 'Transform' is not connected to workflow flow"
}

修复方法：连接节点；如果节点未使用，则将其移除

---

恢复策略

策略 1：重新开始

适用情况：配置严重损坏

步骤：

1. 从 get_node 中记录必填字段
2. 创建最简有效配置
3. 逐步添加功能
4. 每次添加后都进行验证

策略 2：二分查找

适用情况：工作流验证通过，但执行结果不正确

步骤：

1. 移除一半节点
2. 验证并测试
3. 如果正常：问题在已移除的节点中
4. 如果失败：问题在剩余节点中
5. 重复上述步骤，直到定位问题

策略 3：清理过时的连接

适用情况：出现“找不到节点”错误

步骤：

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{
    type: "cleanStaleConnections"
  }]
})

策略 4：使用自动修复

适用情况：可自动解决的验证错误

步骤：

// Preview fixes (default - doesn't apply)
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: false,
  confidenceThreshold: "medium"  // high, medium, low
})

// Review fixes, then apply
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true
})

---

自动修复功能

n8n_autofix_workflow 工具可修复以下类型的问题：

1. expression-format - 表达式缺少 = 前缀（例如，{{ $json.field }} → ={{ $json.field }}）
2. typeversion-correction - 将节点降级到受支持的 typeVersion
3. error-output-config - 移除冲突的 onError 设置
4. node-type-correction - 使用相似度匹配修正未知节点类型（置信度 90% 以上）
5. webhook-missing-path - 为缺少路径配置的 webhook 节点生成 UUID
6. typeversion-upgrade - 智能升级到最新节点版本并自动迁移
7. version-migration - 为需要手动操作的复杂破坏性变更提供指导

置信度等级：high（90% 以上，可安全自动应用）、medium（70-89%，建议审核）、low（低于 70%，需要人工审核）

// Preview all fixes
n8n_autofix_workflow({id: "workflow-id"})

// Only apply high-confidence fixes
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true,
  confidenceThreshold: "high"
})

// Target specific fix types
n8n_autofix_workflow({
  id: "workflow-id",
  fixTypes: ["expression-format", "typeversion-upgrade"],
  applyFixes: true
})

更新后指导：升级版本时，请查看响应中的 postUpdateGuidance 字段，获取分步迁移说明。

---

最佳实践

✅ 应该做

• 每次重大更改后都进行验证
• 完整阅读错误消息
• 逐个修复错误
• 部署前使用 runtime 配置
• 在确认成功前检查 valid 字段
• 对操作符问题信任自动清理功能
• 不确定要求时使用 get_node
• 记录接受的误报

❌ 不应该做

• 激活前跳过验证
• 一次性尝试修复所有错误
• 忽略错误消息
• 开发期间使用 strict 配置（产生过多提示）
• 假定验证已通过（务必检查结果）
• 手动修复自动清理处理的问题
• 带着未解决的错误部署
• 忽略所有警告（其中一些很重要！）

验证通过后运行工作流

validate_workflow 会检查结构、参数和表达式，但绝不会运行任何内容。通过验证的工作流仍可能在真实数据上失败，因此在完成前先运行一次。

使用 Webhook、表单或聊天触发器时： n8n_test_workflow({workflowId}) — 默认的 method: "auto" 会检测触发器并通过 HTTP 触发它（工作流必须处于启用状态）。

没有这类触发器时（手动触发器、计划任务、子工作流），就没有 HTTP 入口。请使用固定数据路径，通过 n8n 自己的 MCP 服务运行（N8N_MCP_ACCESS_TOKEN，n8n 2.34+）：

1. n8n_test_workflow({workflowId, method: "prepare"}) — 列出需要固定数据的节点。
2. 为列出的每个节点构建一个示例项，以节点名称为键，并将每个项包装在 {json: {...}} 中：

   {"When clicking 'Test workflow'": [{"json": {"orderId": "1234", "email": "[email protected]"}}]}
   

   这里常见的错误是使用扁平对象，而不是包含 {json} 项的数组。
3. n8n_test_workflow({workflowId, method: "pinned", pinData}) — 使用这些数据运行工作流并等待结果。

如需快速手动运行而不使用固定数据， method: "direct" 会启动手动执行，并在执行启动后立即返回；请轮询 n8n_executions({action: "get", id: executionId, mode: "error"}) 获取结果。direct 运行不会固定任何数据，因此每个节点都会执行，其进行的任何外部调用都是真实调用 — 而且，即使是 pinned，也只会固定触发器、凭据节点和 HTTP Request 节点。executionMode: "production" 会改变执行上下文，而不是改变是否产生副作用；除非用户要求进行生产运行，否则保持默认值。

method: "auto" 绝不会通过 n8n 的 MCP 服务运行工作流。 对于没有外部触发器的工作流，它会报告这一情况，并列出 prepare/pinned/direct；只有按名称指定时，才会运行这些路由方法。

首次路由运行前需征得同意。 如果工作流的“Available in MCP”设置处于关闭状态，n8n 会拒绝这些调用，并返回 WORKFLOW_NOT_EXPOSED。使用 exposeToMcp: true 重试会开启该设置并再次尝试一次。这是工作流上的可见持久设置（启用该设置会更新工作流，因此可能覆盖并发的 UI 编辑）— 传入该参数前请先征求用户同意。此同意流程只会启用该设置，不会隐式关闭它。再次关闭需要主动操作：n8n_update_partial_workflow({id: workflowId, operations: [{type: "updateSettings", settings: {availableInMCP: false}}]})，或使用 n8n UI 中的开关。

读取结果： 如果运行已启动但随后失败，会返回带有 executionId 的 EXECUTION_FAILED — 请使用 n8n_executions({action: "get", id, mode: "error"}) 检查，并从抛出错误的节点开始修复，然后再次验证并运行。

---

审查现有工作流

在构建时验证（上面的循环）是为了发现自己正在编写的内容中的架构和结构错误。审查现有工作流 — 无论是你自己的，还是别人交给你的 — 是另一项工作：该工作流已经顺利通过 validate_workflow，你要查找的是验证无法发现的问题（隐蔽的连接错误、容易遭受注入攻击的查询、丢弃项的 Switch、Set/Code 反模式、缺失的错误处理路径）。为此，请使用 n8n_get_workflow 获取工作流，并按照 REVIEW_CHECKLIST.md 逐项检查 — 这是一份按严重程度分级的审计清单（必须修复 / 应该修复 / 最好修复），每一项都指向对应的规范技能以供修复。同时运行 n8n_audit_instance，以找出整个实例中的硬编码密钥和未通过身份验证的 Webhook。

---

详细指南

有关完整的错误目录、误报和工作流审查，请参阅：

• ERROR_CATALOG.md - 完整的错误类型列表及示例
• FALSE_POSITIVES.md - 哪些警告可以接受
• REVIEW_CHECKLIST.md - 用于审查现有工作流的分级审计清单

---

摘要

要点：

1. 验证是迭代过程（平均 2-3 轮，23s + 58s）
2. 必须修复错误，警告可按需处理
3. 自动净化会在保存时规范化操作符结构；验证不再因原始结构而报错
4. 默认使用运行时配置；若要获取最佳实践建议，可升级到 ai-friendly/strict
5. 已修复经典误报（≥ 2.63.0）——剩余警告是建议或安全/弃用通知，并非验证器错误
6. 阅读错误消息——其中包含修复指导

验证流程：

1. 验证 → 阅读错误 → 修复 → 再次验证
2. 重复上述步骤，直到验证通过（通常需要 2-3 轮）
3. 查看警告并判断是否可以接受
4. 放心部署

相关技能与工具：

• n8n MCP Tools Expert - 正确使用验证工具
• n8n Expression Syntax - 修复表达式错误
• n8n Node Configuration - 了解必填字段
• n8n_audit_instance - 主动进行安全验证（硬编码密钥、未认证的 Webhook、缺少错误处理、数据保留）