@awesomate/hosting-mcp/skill/awesomate-n8n/references/vendor/validation/SKILL.md

Awesomate MCP server — lets Claude manage your Awesomate WordPress hosting, plan, limits, n8n automations, and build Node/static apps + databases

<!--
  VENDORED from n8n-builder@d293559 (n8n-validation-expert/SKILL.md) — DO NOT EDIT HERE.
  Edit the source in ~/Projects/n8n-builder, then re-run:
    node mcp/scripts/sync-n8n-references.mjs --write

  Awesomate platform overrides — where this file conflicts with
  ../platform-notes.md, platform-notes wins:
    - $env is BLOCKED fleet-wide → use {{ $vars.key || 'fallback' }}
    - Task runners are ON → no $helpers in Code nodes; use HTTP Request nodes
    - Webhook payloads live at $json.body
    - saveExecutionProgress must stay false
-->

# 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