n8n Validation Expert
Expert guide for interpreting and fixing n8n validation errors.
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!
Error Severity Levels
1. Errors (Must Fix)
Blocks workflow execution - Must be resolved before activation
Types:
missing_required - Required field not providedinvalid_value - Value doesn't match allowed optionstype_mismatch - Wrong data type (string instead of number)invalid_reference - Referenced node doesn't existinvalid_expression - Expression syntax error
Example:
{
"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)
Doesn't block execution - Workflow can be activated but may have issues
Types:
best_practice - Recommended but not requireddeprecated - Using old API/featureperformance - Potential performance issue
Example:
{
"type": "best_practice",
"property": "errorHandling",
"message": "Slack API can have rate limits",
"suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"
}
3. Suggestions (Optional)
Nice to have - Improvements that could enhance workflow
Types:
optimization - Could be more efficientalternative - Better way to achieve same result
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)
Example
let config = {
resource: "channel",
operation: "create"
};
const result1 = validate_node({
nodeType: "nodes-base.slack",
config,
profile: "runtime"
});
config.name = "general";
const result2 = validate_node({
nodeType: "nodes-base.slack",
config,
profile: "runtime"
});
config.text = "Hello!";
const result3 = validate_node({
nodeType: "nodes-base.slack",
config,
profile: "runtime"
});
This is normal! Don't be discouraged by multiple iterations.
Validation Profiles
Choose the right profile for your stage:
minimal
Use when: Quick checks during editing
Validates:
- Only required fields
- Basic structure
Pros: Fastest, most permissive
Cons: May miss issues
runtime (RECOMMENDED)
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
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
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
What it means: A required field is not provided
How to fix:
- Use
get_node to see required fields
- Add the missing field to your configuration
- Provide an appropriate value
Example:
{
"type": "missing_required",
"property": "channel",
"message": "Channel name is required"
}
config.channel = "#general";
2. invalid_value
What it means: Value doesn't match allowed options
How to fix:
- Check error message for allowed values
- Use
get_node to see options
- Update to a valid value
Example:
{
"type": "invalid_value",
"property": "operation",
"message": "Operation must be one of: post, update, delete",
"current": "send"
}
config.operation = "post";
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:
{
"type": "type_mismatch",
"property": "limit",
"message": "Expected number, got string",
"current": "100"
}
config.limit = 100;
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:
{
"type": "invalid_expression",
"property": "text",
"message": "Invalid expression: $json.name",
"current": "$json.name"
}
config.text = "={{$json.name}}";
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:
{
"type": "invalid_reference",
"property": "expression",
"message": "Node 'HTTP Requets' does not exist",
"current": "={{$node['HTTP Requets'].json.data}}"
}
config.expression = "={{$node['HTTP Request'].json.data}}";
6. patchNodeField Errors
What it means: A patchNodeField operation failed during n8n_update_partial_workflow
The patchNodeField operation is strict by design — it errors instead of silently continuing when something is wrong. This catches mistakes early but means you need to handle these specific error cases.
Error: Find string not found
The patch's find value doesn't exist in the target field. This usually means the content was already changed, or the find string has a typo.
patchNodeField: find string not found in field "parameters.jsCode"
How to fix: Double-check the exact string. Use n8n_get_workflow to inspect the current field value. Whitespace and line endings matter — if unsure, use regex: true with \s+ for flexible whitespace matching.
Error: Ambiguous match (multiple occurrences)
The find string appears more than once in the field. Without replaceAll: true, this is treated as ambiguous and rejected.
patchNodeField: find string matches 3 times in field "parameters.jsCode" — set replaceAll: true to replace all, or use a more specific find string
How to fix: Either set replaceAll: true if you want to replace all occurrences, or make your find string more specific to match only the intended location.
Error: Invalid regex pattern
When regex: true, the pattern is validated for correctness and safety.
patchNodeField: invalid or unsafe regex pattern
How to fix: Check regex syntax. Nested quantifiers like (a+)+ and overlapping alternations like (\w|\d)+ are rejected as ReDoS risks. Simplify the pattern.
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
What It Fixes
1. Binary Operators (Two Values)
Operators: equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith
Fix: Removes singleValue property (binary operators compare two values)
Before:
{
"type": "boolean",
"operation": "equals",
"singleValue": true
}
Af
