# n8n Validation Expert Expert guide for interpreting n8n editor warnings and execution errors, and reviewing workflow JSON for configuration mistakes. --- ## How This Works You don't have direct access to the user's n8n instance. The user pastes: - **Editor warnings** - red/yellow indicators on nodes, "Problem in node" messages - **Execution errors** - error output from a failed run - **Workflow JSON** - exported or hand-written, to review before import Your job: interpret the message, identify the node and field at fault, and propose an exact fix the user applies in their n8n editor. --- ## Debugging Philosophy **Fix early, recheck often** Debugging is typically iterative: - Expect feedback loops - Usually 2-3 fix → recheck cycles - One error being fixed often reveals the next one **Key insight**: Fixing errors 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 provided - `invalid_value` - Value doesn't match allowed options - `type_mismatch` - Wrong data type (string instead of number) - `invalid_reference` - Referenced node doesn't exist - `invalid_expression` - Expression syntax error **Example** (editor message): ``` Problem in node 'Slack' 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 required - `deprecated` - Using old API/feature - `performance` - Potential performance issue **Example**: Slack API can have rate limits → suggest `onError: 'continueRegularOutput'` with Retry On Fail enabled. ### 3. Suggestions (Optional) **Nice to have** - Improvements that could enhance workflow **Types**: - `optimization` - Could be more efficient - `alternative` - Better way to achieve same result --- ## The Fix-and-Recheck Loop ``` 1. User pastes error / warning ↓ 2. Identify the node and field at fault ↓ 3. Read the error message carefully - it usually names the fix ↓ 4. Propose the exact change (field, value, expression) ↓ 5. User applies it, re-opens the node in the editor or re-executes ↓ 6. Confirm the warning is gone - or interpret the next error ↓ 7. Repeat until clean (usually 2-3 iterations) ``` ### Example ``` // Iteration 1 User: "Problem in node 'Slack': Missing required field 'name'" Fix: Set Channel Name (e.g. "general") in the node panel. // Iteration 2 - user re-opens node, new warning appears User: "Missing required field 'text'" Fix: Set Message Text (e.g. "Hello!"). // Iteration 3 - user re-executes User: "It ran!" ✅ ``` **This is normal!** Don't be discouraged by multiple iterations - fixing one required field often surfaces the next. --- ## Review Methodology When reviewing workflow JSON or a node configuration, check in this order: ### 1. Required fields first Most errors are missing required fields. For each node, confirm the fields its operation needs are present (e.g. HTTP Request needs `url`; Slack post needs `channel` + `text`). ### 2. Value validity Enum values (`resource`, `operation`, `method`) must match allowed options exactly - they are case-sensitive. Check formats (channel names, emails, URLs). ### 3. Data types Numbers as numbers, booleans as booleans - not `"100"` or `"true"`. ### 4. Expressions `{{}}` wrapping (with leading `=` in JSON), correct node names in `$node[...]` references, webhook data under `$json.body`. ### 5. Connections and structure No connections to nodes that don't exist, Switch rules match output count, no accidentally disconnected nodes. **Calibrate depth to stakes**: a quick required-fields pass is fine for dev/test workflows; production workflows deserve the full pass including error handling, retries, and rate limiting. --- ## Common Error Types ### 1. missing_required **What it means**: A required field is not provided **How to fix**: 1. Open the node in the editor - required fields are marked and highlighted when empty 2. Fill in the missing field with an appropriate value **Example**: ``` Error: "Channel name is required" (property: channel) Fix: Set Channel to "#general" ``` ### 2. invalid_value **What it means**: Value doesn't match allowed options **How to fix**: 1. Check the error message for allowed values 2. Check the node's dropdown in the editor for valid options 3. Update to a valid value (match case exactly) **Example**: ``` Error: "Operation must be one of: post, update, delete" (current: "send") Fix: Set Operation to "post" ``` ### 3. type_mismatch **What it means**: Wrong data type for field **How to fix**: 1. Check expected type in error message 2. Convert value to correct type **Example**: ``` Error: "Expected number, got string" (property: limit, current: "100") Fix: limit: 100 (number, not string - remove the quotes in JSON) ``` ### 4. invalid_expression **What it means**: Expression syntax error **How to fix**: 1. Use the n8n Expression Syntax skill 2. Check for missing `{{}}` or typos 3. Verify node/field references **Example**: ``` Error: "Invalid expression: $json.name" (property: text) Fix: "={{$json.name}}" - add the ={{}} wrapper ``` ### 5. invalid_reference **What it means**: Referenced node doesn't exist **How to fix**: 1. Check node name spelling 2. Verify node exists in workflow 3. Update reference to correct name **Example**: ``` Error: "Node 'HTTP Requets' does not exist" Fix: "={{$node['HTTP Request'].json.data}}" - correct the typo ``` --- ## Operator Structure (IF/Switch) The n8n editor normalizes condition operator structures when you save a node. This matters mainly when **hand-writing workflow JSON for import** - get the structure right so conditions behave correctly: ### 1. Binary Operators (Two Values) **Operators**: equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith **Rule**: No `singleValue` property (binary operators compare two values) ```javascript { "type": "boolean", "operation": "equals" // no singleValue ✅ } ``` ### 2. Unary Operators (One Value) **Operators**: isEmpty, isNotEmpty, true, false **Rule**: Must have `singleValue: true` (unary operators check a single value) ```javascript { "type": "boolean", "operation": "isEmpty", "singleValue": true // ✅ Required } ``` ### 3. IF/Switch Metadata IF v2.2+ and Switch v3.2+ expect complete `conditions.options` metadata. The editor adds it on save - if reviewing JSON that was built in the editor, incomplete metadata will be filled in when the user opens and saves the node. ### What the Editor Cannot Fix #### 1. Broken Connections References to non-existent nodes in the `connections` object **Solution**: Remove the stale entry from `connections` (or delete and re-draw the connection in the editor) #### 2. Branch Count Mismatches 3 Switch rules but only 2 output connections **Solution**: Add missing connections or remove extra rules --- ## False Positives ### What Are They? Warnings that are technically "wrong" but acceptable - or plain incorrect - in your use case. ### Structural False Positives (Ignore) #### 1. Community/custom nodes reported as "unknown" Nodes from community packages (e.g. `CUSTOM.*`, `n8n-nodes-*`) show as unknown node types when reviewing JSON outside the instance that has them installed. If the target instance has the package, this is not an error. #### 2. Cycles flagged in polling workflows Loop-back connections (e.g. Wait → check status → loop back) get flagged as circular dependencies. Cycle-based polling is a legitimate pattern - a cycle is only a bug if there's no exit condition. ### Context-Dependent Warnings #### 1. "Missing error handling" **When acceptable**: Simple workflows, testing/development, non-critical notifications **When to fix**: Production workflows handling important data #### 2. "No retry logic" **When acceptable**: APIs with their own retry logic, idempotent operations, manual trigger workflows **When to fix**: Flaky external services, production automation #### 3. "Missing rate limiting" **When acceptable**: Internal APIs with no limits, low-volume workflows **When to fix**: Public APIs, high-volume workflows #### 4. "Unbounded query" **When acceptable**: Small known datasets, aggregation queries, development/testing **When to fix**: Production queries on large tables Full guide: **[FALSE_POSITIVES.md](FALSE_POSITIVES.md)** --- ## Reviewing Workflow JSON Before Import When the user pastes a full workflow, check: 1. **Node configurations** - each node valid (required fields, values, types) 2. **Connections** - no broken references, counts match branch rules 3. **Expressions** - syntax and node references valid 4. **Flow** - logical workflow structure, triggers wired correctly ### Common Workflow-Level Errors #### 1. Broken Connections ``` Connection from 'Transform' to 'NonExistent' - target node not found ``` **Fix**: Remove stale connection or create the missing node #### 2. Circular Dependencies ``` Circular dependency detected: Node A → Node B → Node A ``` **Fix**: Restructure to remove the loop - unless it's intentional cycle-based polling with an exit condition (see False Positives) #### 3. Multiple Start Nodes ``` Multiple trigger nodes found ``` **Fix**: Fine if intentional (e.g. webhook + schedule); otherwise remove extras or split into separate workflows #### 4. Disconnected Nodes ``` Node 'Transform' is not connected to workflow flow ``` **Fix**: Connect node or remove if unused --- ## Recovery Strategies ### Strategy 1: Start Fresh **When**: Configuration is severely broken **Steps**: 1. Note the required fields from a fresh node of the same type in the editor 2. Create minimal valid configuration 3. Add features incrementally 4. Re-execute after each addition ### Strategy 2: Binary Search **When**: Workflow looks valid but executes incorrectly **Steps**: 1. Disable half the nodes 2. Execute and observe 3. If works: problem is in disabled nodes 4. If fails: problem is in remaining nodes 5. Repeat until problem isolated ### Strategy 3: Clean Stale Connections **When**: "Node not found" errors after renaming/deleting nodes **Steps**: 1. In the editor: delete and re-draw the affected connections 2. In JSON: remove entries in the `connections` object whose keys or targets name nodes that no longer exist (connections are keyed by node **name** - renames break them) --- ## Best Practices ### ✅ Do - Recheck after every significant change (re-open node / re-execute) - Read error messages completely - they contain fix guidance - Fix errors iteratively (one at a time) - Fix errors before worrying about warnings - Check required fields first when reviewing JSON - Recognize structural false positives (community nodes, polling cycles) - Document false positives you accept ### ❌ Don't - Activate a workflow with unresolved errors - Try to fix all errors at once - Ignore error messages - Assume a fix worked - confirm the warning is gone - Hand-fix operator structures the editor normalizes on save - Ignore all warnings (some are important!) --- ## Detailed Guides For comprehensive error catalogs and false positive examples: - **[ERROR_CATALOG.md](ERROR_CATALOG.md)** - Complete list of error types with examples - **[FALSE_POSITIVES.md](FALSE_POSITIVES.md)** - When warnings are acceptable --- ## Summary **Key Points**: 1. **Debugging is iterative** (usually 2-3 fix → recheck cycles) 2. **Errors must be fixed**, warnings are optional 3. **The editor normalizes operator structures** on save 4. **Check required fields first**, then values, types, expressions, connections 5. **False positives exist** - learn to recognize them 6. **Read error messages** - they contain fix guidance **Debugging Process**: 1. Interpret error → propose fix → user applies → recheck 2. Repeat until clean (usually 2-3 iterations) 3. Review warnings and decide if acceptable 4. Activate with confidence **Related Skills**: - n8n Expression Syntax - Fix expression errors - n8n Node Configuration - Understand required fields