n8n-validation-expert
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesen8n Validation Expert
n8n 验证专家
Expert guide for interpreting and fixing n8n validation errors.
解读和修复n8n验证错误的专家指南。
Validation Philosophy
验证理念
Validate early, validate often
Validation is typically iterative:
- Expect validation feedback loops
- Usually 2-3 validate → fix cycles
- Average: 23s thinking about errors, 58s fixing them
Key insight: Validation is an iterative process, not one-shot!
尽早验证,频繁验证
验证通常是一个迭代过程:
- 会收到验证反馈循环
- 通常需要2-3次「验证→修复」循环
- 平均耗时:23秒分析错误,58秒修复错误
核心要点:验证是迭代过程,而非一次性操作!
Error Severity Levels
错误严重级别
1. Errors (Must Fix)
1. 错误(必须修复)
Blocks workflow execution - Must be resolved before activation
Types:
- - Required field not provided
missing_required - - Value doesn't match allowed options
invalid_value - - Wrong data type (string instead of number)
type_mismatch - - Referenced node doesn't exist
invalid_reference - - Expression syntax error
invalid_expression
Example:
json
{
"type": "missing_required",
"property": "channel",
"message": "Channel name is required",
"fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)"
}会阻止工作流执行 - 必须在激活前解决
类型:
- - 未提供必填字段
missing_required - - 值不符合允许的选项
invalid_value - - 数据类型错误(例如用字符串代替数字)
type_mismatch - - 引用的节点不存在
invalid_reference - - 表达式语法错误
invalid_expression
示例:
json
{
"type": "missing_required",
"property": "channel",
"message": "Channel name is required",
"fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)"
}2. Warnings (Should Fix)
2. 警告(建议修复)
Doesn't block execution - Workflow can be activated but may have issues
Types:
- - Recommended but not required
best_practice - - Using old API/feature
deprecated - - Potential performance issue
performance
Example:
json
{
"type": "best_practice",
"property": "errorHandling",
"message": "Slack API can have rate limits",
"suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"
}不会阻止执行 - 工作流可以激活,但可能存在问题
类型:
- - 推荐但非强制要求
best_practice - - 使用了旧版API/功能
deprecated - - 存在潜在性能问题
performance
示例:
json
{
"type": "best_practice",
"property": "errorHandling",
"message": "Slack API can have rate limits",
"suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"
}3. Suggestions (Optional)
3. 建议(可选)
Nice to have - Improvements that could enhance workflow
Types:
- - Could be more efficient
optimization - - Better way to achieve same result
alternative
锦上添花 - 可优化工作流的改进建议
类型:
- - 可提升效率
optimization - - 实现相同结果的更佳方式
alternative
The Validation Loop
验证循环
Pattern from Telemetry
遥测数据中的模式
7,841 occurrences of this pattern:
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)该模式出现7841次:
1. 配置节点
↓
2. validate_node(23秒分析错误)
↓
3. 仔细阅读错误信息
↓
4. 修复错误
↓
5. 再次执行validate_node(58秒修复)
↓
6. 重复直到验证通过(通常2-3次迭代)Example
示例
javascript
// 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! ✅This is normal! Don't be discouraged by multiple iterations.
javascript
// 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! ✅这是正常现象! 不要因多次迭代而气馁。
Validation Profiles
验证配置文件
Choose the right profile for your stage:
根据你的阶段选择合适的配置文件:
minimal
minimal
Use when: Quick checks during editing
Validates:
- Only required fields
- Basic structure
Pros: Fastest, most permissive
Cons: May miss issues
适用场景: 编辑过程中的快速检查
验证内容:
- 仅必填字段
- 基础结构
优点: 最快、最宽松
缺点: 可能遗漏问题
runtime (RECOMMENDED)
runtime(推荐)
Use when: Pre-deployment validation
Validates:
- Required fields
- Value types
- Allowed values
- Basic dependencies
Pros: Balanced, catches real errors
Cons: Some edge cases missed
This is the recommended profile for most use cases
适用场景: 部署前验证
验证内容:
- 必填字段
- 值类型
- 允许的值
- 基础依赖
优点: 平衡全面,能捕获实际错误
缺点: 可能遗漏部分边缘情况
这是大多数场景下的推荐配置文件
ai-friendly
ai-friendly
Use when: AI-generated configurations
Validates:
- Same as runtime
- Reduces false positives
- More tolerant of minor issues
Pros: Less noisy for AI workflows
Cons: May allow some questionable configs
适用场景: AI生成的配置
验证内容:
- 与runtime一致
- 减少误报
- 对小问题更宽容
优点: AI工作流中干扰更少
缺点: 可能允许一些有问题的配置
strict
strict
Use when: Production deployment, critical workflows
Validates:
- Everything
- Best practices
- Performance concerns
- Security issues
Pros: Maximum safety
Cons: Many warnings, some false positives
适用场景: 生产部署、关键工作流
验证内容:
- 所有内容
- 最佳实践
- 性能问题
- 安全问题
优点: 安全性最高
缺点: 警告多,存在部分误报
Common Error Types
常见错误类型
1. missing_required
1. missing_required
What it means: A required field is not provided
How to fix:
- Use to see required fields
get_node - Add the missing field to your configuration
- Provide an appropriate value
Example:
javascript
// Error
{
"type": "missing_required",
"property": "channel",
"message": "Channel name is required"
}
// Fix
config.channel = "#general";含义: 未提供必填字段
修复方法:
- 使用查看必填字段
get_node - 在配置中添加缺失的字段
- 提供合适的值
示例:
javascript
// Error
{
"type": "missing_required",
"property": "channel",
"message": "Channel name is required"
}
// Fix
config.channel = "#general";2. invalid_value
2. invalid_value
What it means: Value doesn't match allowed options
How to fix:
- Check error message for allowed values
- Use to see options
get_node - Update to a valid value
Example:
javascript
// Error
{
"type": "invalid_value",
"property": "operation",
"message": "Operation must be one of: post, update, delete",
"current": "send"
}
// Fix
config.operation = "post"; // Use valid operation含义: 值不符合允许的选项
修复方法:
- 查看错误信息中的允许值
- 使用查看选项
get_node - 更新为有效值
示例:
javascript
// Error
{
"type": "invalid_value",
"property": "operation",
"message": "Operation must be one of: post, update, delete",
"current": "send"
}
// Fix
config.operation = "post"; // Use valid operation3. type_mismatch
3. type_mismatch
What it means: Wrong data type for field
How to fix:
- Check expected type in error message
- Convert value to correct type
Example:
javascript
// Error
{
"type": "type_mismatch",
"property": "limit",
"message": "Expected number, got string",
"current": "100"
}
// Fix
config.limit = 100; // Number, not string含义: 字段数据类型错误
修复方法:
- 查看错误信息中的预期类型
- 将值转换为正确类型
示例:
javascript
// Error
{
"type": "type_mismatch",
"property": "limit",
"message": "Expected number, got string",
"current": "100"
}
// Fix
config.limit = 100; // Number, not string4. invalid_expression
4. invalid_expression
What it means: Expression syntax error
How to fix:
- Use n8n Expression Syntax skill
- Check for missing or typos
{{}} - Verify node/field references
Example:
javascript
// Error
{
"type": "invalid_expression",
"property": "text",
"message": "Invalid expression: $json.name",
"current": "$json.name"
}
// Fix
config.text = "={{$json.name}}"; // Add {{}}含义: 表达式语法错误
修复方法:
- 使用n8n表达式语法技能
- 检查是否缺少或拼写错误
{{}} - 验证节点/字段引用
示例:
javascript
// Error
{
"type": "invalid_expression",
"property": "text",
"message": "Invalid expression: $json.name",
"current": "$json.name"
}
// Fix
config.text = "={{$json.name}}"; // Add {{}}5. invalid_reference
5. invalid_reference
What it means: Referenced node doesn't exist
How to fix:
- Check node name spelling
- Verify node exists in workflow
- Update reference to correct name
Example:
javascript
// Error
{
"type": "invalid_reference",
"property": "expression",
"message": "Node 'HTTP Requets' does not exist",
"current": "={{$node['HTTP Requets'].json.data}}"
}
// Fix - correct typo
config.expression = "={{$node['HTTP Request'].json.data}}";含义: 引用的节点不存在
修复方法:
- 检查节点名称拼写
- 验证节点是否存在于工作流中
- 更新引用为正确的名称
示例:
javascript
// Error
{
"type": "invalid_reference",
"property": "expression",
"message": "Node 'HTTP Requets' does not exist",
"current": "={{$node['HTTP Requets'].json.data}}"
}
// Fix - correct typo
config.expression = "={{$node['HTTP Request'].json.data}}";Auto-Sanitization System
自动清理系统
What It Does
功能
Automatically fixes common operator structure issues on ANY workflow update
Runs when:
n8n_create_workflown8n_update_partial_workflow- Any workflow save operation
在任何工作流更新时自动修复常见操作符结构问题
运行时机:
n8n_create_workflown8n_update_partial_workflow- 任何工作流保存操作
What It Fixes
修复内容
1. Binary Operators (Two Values)
1. 二元操作符(两个值)
Operators: equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith
Fix: Removes property (binary operators compare two values)
singleValueBefore:
javascript
{
"type": "boolean",
"operation": "equals",
"singleValue": true // ❌ Wrong!
}After (automatic):
javascript
{
"type": "boolean",
"operation": "equals"
// singleValue removed ✅
}操作符: equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith
修复: 移除属性(二元操作符用于比较两个值)
singleValue修复前:
javascript
{
"type": "boolean",
"operation": "equals",
"singleValue": true // ❌ Wrong!
}修复后(自动):
javascript
{
"type": "boolean",
"operation": "equals"
// singleValue removed ✅
}2. Unary Operators (One Value)
2. 一元操作符(一个值)
Operators: isEmpty, isNotEmpty, true, false
Fix: Adds (unary operators check single value)
singleValue: trueBefore:
javascript
{
"type": "boolean",
"operation": "isEmpty"
// Missing singleValue ❌
}After (automatic):
javascript
{
"type": "boolean",
"operation": "isEmpty",
"singleValue": true // ✅ Added
}操作符: isEmpty, isNotEmpty, true, false
修复: 添加(一元操作符用于检查单个值)
singleValue: true修复前:
javascript
{
"type": "boolean",
"operation": "isEmpty"
// Missing singleValue ❌
}修复后(自动):
javascript
{
"type": "boolean",
"operation": "isEmpty",
"singleValue": true // ✅ Added
}3. IF/Switch Metadata
3. IF/Switch 元数据
Fix: Adds complete metadata for IF v2.2+ and Switch v3.2+
conditions.options修复: 为IF v2.2+和Switch v3.2+添加完整的元数据
conditions.optionsWhat It CANNOT Fix
无法修复的内容
1. Broken Connections
1. 损坏的连接
References to non-existent nodes
Solution: Use operation in
cleanStaleConnectionsn8n_update_partial_workflow引用不存在的节点
解决方案: 在中使用操作
n8n_update_partial_workflowcleanStaleConnections2. Branch Count Mismatches
2. 分支数量不匹配
3 Switch rules but only 2 output connections
Solution: Add missing connections or remove extra rules
3个Switch规则但只有2个输出连接
解决方案: 添加缺失的连接或移除多余的规则
3. Paradoxical Corrupt States
3. 矛盾的损坏状态
API returns corrupt data but rejects updates
Solution: May require manual database intervention
API返回损坏数据但拒绝更新
解决方案: 可能需要手动干预数据库
False Positives
误报
What Are They?
定义
Validation warnings that are technically "wrong" but acceptable in your use case
在你的使用场景中技术上「错误」但可接受的验证警告
Common False Positives
常见误报
1. "Missing error handling"
1. "Missing error handling"
Warning: No error handling configured
When acceptable:
- Simple workflows where failures are obvious
- Testing/development workflows
- Non-critical notifications
When to fix: Production workflows handling important data
警告: 未配置错误处理
可接受场景:
- 简单工作流,失败情况明显
- 测试/开发工作流
- 非关键通知
需要修复的场景: 处理重要数据的生产工作流
2. "No retry logic"
2. "No retry logic"
Warning: Node doesn't retry on failure
When acceptable:
- APIs with their own retry logic
- Idempotent operations
- Manual trigger workflows
When to fix: Flaky external services, production automation
警告: 节点在失败时不重试
可接受场景:
- 自身带有重试逻辑的API
- 幂等操作
- 手动触发的工作流
需要修复的场景: 不稳定的外部服务、生产自动化
3. "Missing rate limiting"
3. "Missing rate limiting"
Warning: No rate limiting for API calls
When acceptable:
- Internal APIs with no limits
- Low-volume workflows
- APIs with server-side rate limiting
When to fix: Public APIs, high-volume workflows
警告: API调用未设置速率限制
可接受场景:
- 无限制的内部API
- 低流量工作流
- 服务端已设置速率限制的API
需要修复的场景: 公共API、高流量工作流
4. "Unbounded query"
4. "Unbounded query"
Warning: SELECT without LIMIT
When acceptable:
- Small known datasets
- Aggregation queries
- Development/testing
When to fix: Production queries on large tables
警告: SELECT查询未设置LIMIT
可接受场景:
- 已知的小型数据集
- 聚合查询
- 开发/测试
需要修复的场景: 生产环境中对大表的查询
Reducing False Positives
减少误报
Use profile:
ai-friendlyjavascript
validate_node({
nodeType: "nodes-base.slack",
config: {...},
profile: "ai-friendly" // Fewer false positives
})使用配置文件:
ai-friendlyjavascript
validate_node({
nodeType: "nodes-base.slack",
config: {...},
profile: "ai-friendly" // Fewer false positives
})Validation Result Structure
验证结果结构
Complete Response
完整响应
javascript
{
"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
}
}javascript
{
"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
}
}How to Read It
解读方法
1. Check valid
field
valid1. 检查valid
字段
validjavascript
if (result.valid) {
// ✅ Configuration is valid
} else {
// ❌ Has errors - must fix before deployment
}javascript
if (result.valid) {
// ✅ Configuration is valid
} else {
// ❌ Has errors - must fix before deployment
}2. Fix errors first
2. 优先修复错误
javascript
result.errors.forEach(error => {
console.log(`Error in ${error.property}: ${error.message}`);
console.log(`Fix: ${error.fix}`);
});javascript
result.errors.forEach(error => {
console.log(`Error in ${error.property}: ${error.message}`);
console.log(`Fix: ${error.fix}`);
});3. Review warnings
3. 查看警告
javascript
result.warnings.forEach(warning => {
console.log(`Warning: ${warning.message}`);
console.log(`Suggestion: ${warning.suggestion}`);
// Decide if you need to address this
});javascript
result.warnings.forEach(warning => {
console.log(`Warning: ${warning.message}`);
console.log(`Suggestion: ${warning.suggestion}`);
// Decide if you need to address this
});4. Consider suggestions
4. 考虑建议
javascript
// Optional improvements
// Not required but may enhance workflowjavascript
// Optional improvements
// Not required but may enhance workflowWorkflow Validation
工作流验证
validate_workflow (Structure)
validate_workflow(结构)
Validates entire workflow, not just individual nodes
Checks:
- Node configurations - Each node valid
- Connections - No broken references
- Expressions - Syntax and references valid
- Flow - Logical workflow structure
Example:
javascript
validate_workflow({
workflow: {
nodes: [...],
connections: {...}
},
options: {
validateNodes: true,
validateConnections: true,
validateExpressions: true,
profile: "runtime"
}
})验证整个工作流,而非单个节点
检查内容:
- 节点配置 - 每个节点都有效
- 连接 - 无损坏的引用
- 表达式 - 语法和引用有效
- 流程 - 工作流结构逻辑合理
示例:
javascript
validate_workflow({
workflow: {
nodes: [...],
connections: {...}
},
options: {
validateNodes: true,
validateConnections: true,
validateExpressions: true,
profile: "runtime"
}
})Common Workflow Errors
常见工作流错误
1. Broken Connections
1. 损坏的连接
json
{
"error": "Connection from 'Transform' to 'NonExistent' - target node not found"
}Fix: Remove stale connection or create missing node
json
{
"error": "Connection from 'Transform' to 'NonExistent' - target node not found"
}修复: 移除失效连接或创建缺失的节点
2. Circular Dependencies
2. 循环依赖
json
{
"error": "Circular dependency detected: Node A → Node B → Node A"
}Fix: Restructure workflow to remove loop
json
{
"error": "Circular dependency detected: Node A → Node B → Node A"
}修复: 重构工作流以移除循环
3. Multiple Start Nodes
3. 多个起始节点
json
{
"warning": "Multiple trigger nodes found - only one will execute"
}Fix: Remove extra triggers or split into separate workflows
json
{
"warning": "Multiple trigger nodes found - only one will execute"
}修复: 移除多余的触发器或拆分为单独的工作流
4. Disconnected Nodes
4. 未连接的节点
json
{
"warning": "Node 'Transform' is not connected to workflow flow"
}Fix: Connect node or remove if unused
json
{
"warning": "Node 'Transform' is not connected to workflow flow"
}修复: 连接节点或移除未使用的节点
Recovery Strategies
恢复策略
Strategy 1: Start Fresh
策略1:重新开始
When: Configuration is severely broken
Steps:
- Note required fields from
get_node - Create minimal valid configuration
- Add features incrementally
- Validate after each addition
适用场景: 配置严重损坏
步骤:
- 从中记录必填字段
get_node - 创建最小的有效配置
- 逐步添加功能
- 每次添加后进行验证
Strategy 2: Binary Search
策略2:二分查找
When: Workflow validates but executes incorrectly
Steps:
- Remove half the nodes
- Validate and test
- If works: problem is in removed nodes
- If fails: problem is in remaining nodes
- Repeat until problem isolated
适用场景: 工作流验证通过但执行出错
步骤:
- 移除一半节点
- 验证并测试
- 如果正常:问题在移除的节点中
- 如果失败:问题在剩余的节点中
- 重复直到定位问题
Strategy 3: Clean Stale Connections
策略3:清理失效连接
When: "Node not found" errors
Steps:
javascript
n8n_update_partial_workflow({
id: "workflow-id",
operations: [{
type: "cleanStaleConnections"
}]
})适用场景: 出现「节点未找到」错误
步骤:
javascript
n8n_update_partial_workflow({
id: "workflow-id",
operations: [{
type: "cleanStaleConnections"
}]
})Strategy 4: Use Auto-fix
策略4:使用自动修复
When: Operator structure errors
Steps:
javascript
n8n_autofix_workflow({
id: "workflow-id",
applyFixes: false // Preview first
})
// Review fixes, then apply
n8n_autofix_workflow({
id: "workflow-id",
applyFixes: true
})适用场景: 操作符结构错误
步骤:
javascript
n8n_autofix_workflow({
id: "workflow-id",
applyFixes: false // Preview first
})
// Review fixes, then apply
n8n_autofix_workflow({
id: "workflow-id",
applyFixes: true
})Best Practices
最佳实践
✅ Do
✅ 建议
- Validate after every significant change
- Read error messages completely
- Fix errors iteratively (one at a time)
- Use profile for pre-deployment
runtime - Check field before assuming success
valid - Trust auto-sanitization for operator issues
- Use when unclear about requirements
get_node - Document false positives you accept
- 每次重大变更后进行验证
- 完整阅读错误信息
- 迭代修复错误(一次修复一个)
- 部署前使用配置文件
runtime - 不要假设验证通过,务必检查结果
- 信任自动清理功能处理操作符问题
- 当对要求不明确时使用
get_node - 记录你接受的误报
❌ Don't
❌ 不建议
- Skip validation before activation
- Try to fix all errors at once
- Ignore error messages
- Use profile during development (too noisy)
strict - Assume validation passed (always check result)
- Manually fix auto-sanitization issues
- Deploy with unresolved errors
- Ignore all warnings (some are important!)
- 激活前跳过验证
- 尝试一次性修复所有错误
- 忽略错误信息
- 开发期间使用配置文件(干扰过多)
strict - 假设验证通过(务必检查结果)
- 手动修复自动清理可处理的问题
- 带着未解决的错误部署
- 忽略所有警告(部分警告很重要!)
Detailed Guides
详细指南
For comprehensive error catalogs and false positive examples:
- ERROR_CATALOG.md - Complete list of error types with examples
- FALSE_POSITIVES.md - When warnings are acceptable
如需完整的错误目录和误报示例:
- ERROR_CATALOG.md - 完整的错误类型列表及示例
- FALSE_POSITIVES.md - 哪些警告可接受
Summary
总结
Key Points:
- Validation is iterative (avg 2-3 cycles, 23s + 58s)
- Errors must be fixed, warnings are optional
- Auto-sanitization fixes operator structures automatically
- Use runtime profile for balanced validation
- False positives exist - learn to recognize them
- Read error messages - they contain fix guidance
Validation Process:
- Validate → Read errors → Fix → Validate again
- Repeat until valid (usually 2-3 iterations)
- Review warnings and decide if acceptable
- Deploy with confidence
Related Skills:
- n8n MCP Tools Expert - Use validation tools correctly
- n8n Expression Syntax - Fix expression errors
- n8n Node Configuration - Understand required fields
核心要点:
- 验证是迭代过程(平均2-3次循环,23秒+58秒)
- 错误必须修复,警告可选
- 自动清理可自动修复操作符结构
- 使用runtime配置文件进行平衡验证
- 存在误报 - 学会识别它们
- 阅读错误信息 - 其中包含修复指导
验证流程:
- 验证 → 阅读错误 → 修复 → 再次验证
- 重复直到验证通过(通常2-3次迭代)
- 查看警告并决定是否处理
- 放心部署
相关技能:
- n8n MCP Tools Expert - 正确使用验证工具
- n8n Expression Syntax - 修复表达式错误
- n8n Node Configuration - 理解必填字段