Interpret validation errors and guide fixing them. Use when encountering validation errors, validation warnings, false positives, operator structure issues, or need help understanding validation results. Also use when asking about validation profiles, error types, or the validation loop process.
Add this skill
npx mdskills install czlonkowski/n8n-validation-expertComprehensive validation guidance with clear error taxonomy, iterative workflow patterns, and practical recovery strategies
1---2name: n8n-validation-expert3description: Interpret validation errors and guide fixing them. Use when encountering validation errors, validation warnings, false positives, operator structure issues, or need help understanding validation results. Also use when asking about validation profiles, error types, or the validation loop process.4---56# n8n Validation Expert78Expert guide for interpreting and fixing n8n validation errors.910---1112## Validation Philosophy1314**Validate early, validate often**1516Validation is typically iterative:17- Expect validation feedback loops18- Usually 2-3 validate → fix cycles19- Average: 23s thinking about errors, 58s fixing them2021**Key insight**: Validation is an iterative process, not one-shot!2223---2425## Error Severity Levels2627### 1. Errors (Must Fix)28**Blocks workflow execution** - Must be resolved before activation2930**Types**:31- `missing_required` - Required field not provided32- `invalid_value` - Value doesn't match allowed options33- `type_mismatch` - Wrong data type (string instead of number)34- `invalid_reference` - Referenced node doesn't exist35- `invalid_expression` - Expression syntax error3637**Example**:38```json39{40 "type": "missing_required",41 "property": "channel",42 "message": "Channel name is required",43 "fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)"44}45```4647### 2. Warnings (Should Fix)48**Doesn't block execution** - Workflow can be activated but may have issues4950**Types**:51- `best_practice` - Recommended but not required52- `deprecated` - Using old API/feature53- `performance` - Potential performance issue5455**Example**:56```json57{58 "type": "best_practice",59 "property": "errorHandling",60 "message": "Slack API can have rate limits",61 "suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"62}63```6465### 3. Suggestions (Optional)66**Nice to have** - Improvements that could enhance workflow6768**Types**:69- `optimization` - Could be more efficient70- `alternative` - Better way to achieve same result7172---7374## The Validation Loop7576### Pattern from Telemetry77**7,841 occurrences** of this pattern:7879```801. Configure node81 ↓822. validate_node (23 seconds thinking about errors)83 ↓843. Read error messages carefully85 ↓864. Fix errors87 ↓885. validate_node again (58 seconds fixing)89 ↓906. Repeat until valid (usually 2-3 iterations)91```9293### Example94```javascript95// Iteration 196let config = {97 resource: "channel",98 operation: "create"99};100101const result1 = validate_node({102 nodeType: "nodes-base.slack",103 config,104 profile: "runtime"105});106// → Error: Missing "name"107108// ⏱️ 23 seconds thinking...109110// Iteration 2111config.name = "general";112113const result2 = validate_node({114 nodeType: "nodes-base.slack",115 config,116 profile: "runtime"117});118// → Error: Missing "text"119120// ⏱️ 58 seconds fixing...121122// Iteration 3123config.text = "Hello!";124125const result3 = validate_node({126 nodeType: "nodes-base.slack",127 config,128 profile: "runtime"129});130// → Valid! ✅131```132133**This is normal!** Don't be discouraged by multiple iterations.134135---136137## Validation Profiles138139Choose the right profile for your stage:140141### minimal142**Use when**: Quick checks during editing143144**Validates**:145- Only required fields146- Basic structure147148**Pros**: Fastest, most permissive149**Cons**: May miss issues150151### runtime (RECOMMENDED)152**Use when**: Pre-deployment validation153154**Validates**:155- Required fields156- Value types157- Allowed values158- Basic dependencies159160**Pros**: Balanced, catches real errors161**Cons**: Some edge cases missed162163**This is the recommended profile for most use cases**164165### ai-friendly166**Use when**: AI-generated configurations167168**Validates**:169- Same as runtime170- Reduces false positives171- More tolerant of minor issues172173**Pros**: Less noisy for AI workflows174**Cons**: May allow some questionable configs175176### strict177**Use when**: Production deployment, critical workflows178179**Validates**:180- Everything181- Best practices182- Performance concerns183- Security issues184185**Pros**: Maximum safety186**Cons**: Many warnings, some false positives187188---189190## Common Error Types191192### 1. missing_required193**What it means**: A required field is not provided194195**How to fix**:1961. Use `get_node` to see required fields1972. Add the missing field to your configuration1983. Provide an appropriate value199200**Example**:201```javascript202// Error203{204 "type": "missing_required",205 "property": "channel",206 "message": "Channel name is required"207}208209// Fix210config.channel = "#general";211```212213### 2. invalid_value214**What it means**: Value doesn't match allowed options215216**How to fix**:2171. Check error message for allowed values2182. Use `get_node` to see options2193. Update to a valid value220221**Example**:222```javascript223// Error224{225 "type": "invalid_value",226 "property": "operation",227 "message": "Operation must be one of: post, update, delete",228 "current": "send"229}230231// Fix232config.operation = "post"; // Use valid operation233```234235### 3. type_mismatch236**What it means**: Wrong data type for field237238**How to fix**:2391. Check expected type in error message2402. Convert value to correct type241242**Example**:243```javascript244// Error245{246 "type": "type_mismatch",247 "property": "limit",248 "message": "Expected number, got string",249 "current": "100"250}251252// Fix253config.limit = 100; // Number, not string254```255256### 4. invalid_expression257**What it means**: Expression syntax error258259**How to fix**:2601. Use n8n Expression Syntax skill2612. Check for missing `{{}}` or typos2623. Verify node/field references263264**Example**:265```javascript266// Error267{268 "type": "invalid_expression",269 "property": "text",270 "message": "Invalid expression: $json.name",271 "current": "$json.name"272}273274// Fix275config.text = "={{$json.name}}"; // Add {{}}276```277278### 5. invalid_reference279**What it means**: Referenced node doesn't exist280281**How to fix**:2821. Check node name spelling2832. Verify node exists in workflow2843. Update reference to correct name285286**Example**:287```javascript288// Error289{290 "type": "invalid_reference",291 "property": "expression",292 "message": "Node 'HTTP Requets' does not exist",293 "current": "={{$node['HTTP Requets'].json.data}}"294}295296// Fix - correct typo297config.expression = "={{$node['HTTP Request'].json.data}}";298```299300---301302## Auto-Sanitization System303304### What It Does305**Automatically fixes common operator structure issues** on ANY workflow update306307**Runs when**:308- `n8n_create_workflow`309- `n8n_update_partial_workflow`310- Any workflow save operation311312### What It Fixes313314#### 1. Binary Operators (Two Values)315**Operators**: equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith316317**Fix**: Removes `singleValue` property (binary operators compare two values)318319**Before**:320```javascript321{322 "type": "boolean",323 "operation": "equals",324 "singleValue": true // ❌ Wrong!325}326```327328**After** (automatic):329```javascript330{331 "type": "boolean",332 "operation": "equals"333 // singleValue removed ✅334}335```336337#### 2. Unary Operators (One Value)338**Operators**: isEmpty, isNotEmpty, true, false339340**Fix**: Adds `singleValue: true` (unary operators check single value)341342**Before**:343```javascript344{345 "type": "boolean",346 "operation": "isEmpty"347 // Missing singleValue ❌348}349```350351**After** (automatic):352```javascript353{354 "type": "boolean",355 "operation": "isEmpty",356 "singleValue": true // ✅ Added357}358```359360#### 3. IF/Switch Metadata361**Fix**: Adds complete `conditions.options` metadata for IF v2.2+ and Switch v3.2+362363### What It CANNOT Fix364365#### 1. Broken Connections366References to non-existent nodes367368**Solution**: Use `cleanStaleConnections` operation in `n8n_update_partial_workflow`369370#### 2. Branch Count Mismatches3713 Switch rules but only 2 output connections372373**Solution**: Add missing connections or remove extra rules374375#### 3. Paradoxical Corrupt States376API returns corrupt data but rejects updates377378**Solution**: May require manual database intervention379380---381382## False Positives383384### What Are They?385Validation warnings that are technically "wrong" but acceptable in your use case386387### Common False Positives388389#### 1. "Missing error handling"390**Warning**: No error handling configured391392**When acceptable**:393- Simple workflows where failures are obvious394- Testing/development workflows395- Non-critical notifications396397**When to fix**: Production workflows handling important data398399#### 2. "No retry logic"400**Warning**: Node doesn't retry on failure401402**When acceptable**:403- APIs with their own retry logic404- Idempotent operations405- Manual trigger workflows406407**When to fix**: Flaky external services, production automation408409#### 3. "Missing rate limiting"410**Warning**: No rate limiting for API calls411412**When acceptable**:413- Internal APIs with no limits414- Low-volume workflows415- APIs with server-side rate limiting416417**When to fix**: Public APIs, high-volume workflows418419#### 4. "Unbounded query"420**Warning**: SELECT without LIMIT421422**When acceptable**:423- Small known datasets424- Aggregation queries425- Development/testing426427**When to fix**: Production queries on large tables428429### Reducing False Positives430431**Use `ai-friendly` profile**:432```javascript433validate_node({434 nodeType: "nodes-base.slack",435 config: {...},436 profile: "ai-friendly" // Fewer false positives437})438```439440---441442## Validation Result Structure443444### Complete Response445```javascript446{447 "valid": false,448 "errors": [449 {450 "type": "missing_required",451 "property": "channel",452 "message": "Channel name is required",453 "fix": "Provide a channel name (lowercase, no spaces)"454 }455 ],456 "warnings": [457 {458 "type": "best_practice",459 "property": "errorHandling",460 "message": "Slack API can have rate limits",461 "suggestion": "Add onError: 'continueRegularOutput'"462 }463 ],464 "suggestions": [465 {466 "type": "optimization",467 "message": "Consider using batch operations for multiple messages"468 }469 ],470 "summary": {471 "hasErrors": true,472 "errorCount": 1,473 "warningCount": 1,474 "suggestionCount": 1475 }476}477```478479### How to Read It480481#### 1. Check `valid` field482```javascript483if (result.valid) {484 // ✅ Configuration is valid485} else {486 // ❌ Has errors - must fix before deployment487}488```489490#### 2. Fix errors first491```javascript492result.errors.forEach(error => {493 console.log(`Error in ${error.property}: ${error.message}`);494 console.log(`Fix: ${error.fix}`);495});496```497498#### 3. Review warnings499```javascript500result.warnings.forEach(warning => {501 console.log(`Warning: ${warning.message}`);502 console.log(`Suggestion: ${warning.suggestion}`);503 // Decide if you need to address this504});505```506507#### 4. Consider suggestions508```javascript509// Optional improvements510// Not required but may enhance workflow511```512513---514515## Workflow Validation516517### validate_workflow (Structure)518**Validates entire workflow**, not just individual nodes519520**Checks**:5211. **Node configurations** - Each node valid5222. **Connections** - No broken references5233. **Expressions** - Syntax and references valid5244. **Flow** - Logical workflow structure525526**Example**:527```javascript528validate_workflow({529 workflow: {530 nodes: [...],531 connections: {...}532 },533 options: {534 validateNodes: true,535 validateConnections: true,536 validateExpressions: true,537 profile: "runtime"538 }539})540```541542### Common Workflow Errors543544#### 1. Broken Connections545```json546{547 "error": "Connection from 'Transform' to 'NonExistent' - target node not found"548}549```550551**Fix**: Remove stale connection or create missing node552553#### 2. Circular Dependencies554```json555{556 "error": "Circular dependency detected: Node A → Node B → Node A"557}558```559560**Fix**: Restructure workflow to remove loop561562#### 3. Multiple Start Nodes563```json564{565 "warning": "Multiple trigger nodes found - only one will execute"566}567```568569**Fix**: Remove extra triggers or split into separate workflows570571#### 4. Disconnected Nodes572```json573{574 "warning": "Node 'Transform' is not connected to workflow flow"575}576```577578**Fix**: Connect node or remove if unused579580---581582## Recovery Strategies583584### Strategy 1: Start Fresh585**When**: Configuration is severely broken586587**Steps**:5881. Note required fields from `get_node`5892. Create minimal valid configuration5903. Add features incrementally5914. Validate after each addition592593### Strategy 2: Binary Search594**When**: Workflow validates but executes incorrectly595596**Steps**:5971. Remove half the nodes5982. Validate and test5993. If works: problem is in removed nodes6004. If fails: problem is in remaining nodes6015. Repeat until problem isolated602603### Strategy 3: Clean Stale Connections604**When**: "Node not found" errors605606**Steps**:607```javascript608n8n_update_partial_workflow({609 id: "workflow-id",610 operations: [{611 type: "cleanStaleConnections"612 }]613})614```615616### Strategy 4: Use Auto-fix617**When**: Operator structure errors618619**Steps**:620```javascript621n8n_autofix_workflow({622 id: "workflow-id",623 applyFixes: false // Preview first624})625626// Review fixes, then apply627n8n_autofix_workflow({628 id: "workflow-id",629 applyFixes: true630})631```632633---634635## Best Practices636637### ✅ Do638639- Validate after every significant change640- Read error messages completely641- Fix errors iteratively (one at a time)642- Use `runtime` profile for pre-deployment643- Check `valid` field before assuming success644- Trust auto-sanitization for operator issues645- Use `get_node` when unclear about requirements646- Document false positives you accept647648### ❌ Don't649650- Skip validation before activation651- Try to fix all errors at once652- Ignore error messages653- Use `strict` profile during development (too noisy)654- Assume validation passed (always check result)655- Manually fix auto-sanitization issues656- Deploy with unresolved errors657- Ignore all warnings (some are important!)658659---660661## Detailed Guides662663For comprehensive error catalogs and false positive examples:664665- **[ERROR_CATALOG.md](ERROR_CATALOG.md)** - Complete list of error types with examples666- **[FALSE_POSITIVES.md](FALSE_POSITIVES.md)** - When warnings are acceptable667668---669670## Summary671672**Key Points**:6731. **Validation is iterative** (avg 2-3 cycles, 23s + 58s)6742. **Errors must be fixed**, warnings are optional6753. **Auto-sanitization** fixes operator structures automatically6764. **Use runtime profile** for balanced validation6775. **False positives exist** - learn to recognize them6786. **Read error messages** - they contain fix guidance679680**Validation Process**:6811. Validate → Read errors → Fix → Validate again6822. Repeat until valid (usually 2-3 iterations)6833. Review warnings and decide if acceptable6844. Deploy with confidence685686**Related Skills**:687- n8n MCP Tools Expert - Use validation tools correctly688- n8n Expression Syntax - Fix expression errors689- n8n Node Configuration - Understand required fields690
Full transparency — inspect the skill content before installing.