n8n Validation Expert

Validation Philosophy

• Expect validation feedback loops
• Usually 2-3 validate → fix cycles
• Average: 23s thinking about errors, 58s fixing them

Error Severity Levels

1. Errors (Must Fix)

• 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

{
  "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)

• best_practice

  - Recommended but not required

• deprecated

  - Using old API/feature

• performance

  - Potential performance issue

{
  "type": "best_practice",
  "property": "errorHandling",
  "message": "Slack API can have rate limits",
  "suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"
}

3. Suggestions (Optional)

• optimization

  - Could be more efficient

• alternative

  - Better way to achieve same result

The Validation Loop

Pattern from Telemetry

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

// 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

minimal

• Only required fields
• Basic structure

runtime (RECOMMENDED)

• Required fields
• Value types
• Allowed values
• Basic dependencies

ai-friendly

• Same as runtime
• Reduces false positives
• More tolerant of minor issues

strict

• Everything
• Best practices
• Performance concerns
• Security issues

Common Error Types

1. missing_required

1. Use

   get_node

   to see required fields
2. Add the missing field to your configuration
3. Provide an appropriate value

// Error
{
  "type": "missing_required",
  "property": "channel",
  "message": "Channel name is required"
}

// Fix
config.channel = "#general";

2. invalid_value

1. Check error message for allowed values
2. Use

   get_node

   to see options
3. Update to a valid value

// Error
{
  "type": "invalid_value",
  "property": "operation",
  "message": "Operation must be one of: post, update, delete",
  "current": "send"
}

// Fix
config.operation = "post";  // Use valid operation

3. type_mismatch

1. Check expected type in error message
2. Convert value to correct type

// Error
{
  "type": "type_mismatch",
  "property": "limit",
  "message": "Expected number, got string",
  "current": "100"
}

// Fix
config.limit = 100;  // Number, not string

4. invalid_expression

1. Use n8n Expression Syntax skill
2. Check for missing

   {{}}

   or typos
3. Verify node/field references

// Error
{
  "type": "invalid_expression",
  "property": "text",
  "message": "Invalid expression: $json.name",
  "current": "$json.name"
}

// Fix
config.text = "={{$json.name}}";  // Add {{}}

5. invalid_reference

1. Check node name spelling
2. Verify node exists in workflow
3. Update reference to correct name

// 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

• n8n_create_workflow

• n8n_update_partial_workflow

• Any workflow save operation

What It Fixes

1. Binary Operators (Two Values)

singleValue

{
  "type": "boolean",
  "operation": "equals",
  "singleValue": true  // ❌ Wrong!
}

{
  "type": "boolean",
  "operation": "equals"
  // singleValue removed ✅
}

2. Unary Operators (One Value)

singleValue: true

{
  "type": "boolean",
  "operation": "isEmpty"
  // Missing singleValue ❌
}

{
  "type": "boolean",
  "operation": "isEmpty",
  "singleValue": true  // ✅ Added
}

3. IF/Switch Metadata

conditions.options

What It CANNOT Fix

1. Broken Connections

cleanStaleConnections

n8n_update_partial_workflow

2. Branch Count Mismatches

3. Paradoxical Corrupt States

False Positives

What Are They?

Common False Positives

1. "Missing error handling"

• Simple workflows where failures are obvious
• Testing/development workflows
• Non-critical notifications

2. "No retry logic"

• APIs with their own retry logic
• Idempotent operations
• Manual trigger workflows

3. "Missing rate limiting"

• Internal APIs with no limits
• Low-volume workflows
• APIs with server-side rate limiting

4. "Unbounded query"

• Small known datasets
• Aggregation queries
• Development/testing

Reducing False Positives

ai-friendly

validate_node({
  nodeType: "nodes-base.slack",
  config: {...},
  profile: "ai-friendly"  // Fewer false positives
})

Validation Result Structure

Complete Response

{
  "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

if (result.valid) {
  // ✅ Configuration is valid
} else {
  // ❌ Has errors - must fix before deployment
}

2. Fix errors first

result.errors.forEach(error => {
  console.log(`Error in ${error.property}: ${error.message}`);
  console.log(`Fix: ${error.fix}`);
});

3. Review warnings

result.warnings.forEach(warning => {
  console.log(`Warning: ${warning.message}`);
  console.log(`Suggestion: ${warning.suggestion}`);
  // Decide if you need to address this
});

4. Consider suggestions

// Optional improvements
// Not required but may enhance workflow

Workflow Validation

validate_workflow (Structure)

1. Node configurations - Each node valid
2. Connections - No broken references
3. Expressions - Syntax and references valid
4. Flow - Logical workflow structure

validate_workflow({
  workflow: {
    nodes: [...],
    connections: {...}
  },
  options: {
    validateNodes: true,
    validateConnections: true,
    validateExpressions: true,
    profile: "runtime"
  }
})

Common Workflow Errors

1. Broken Connections

{
  "error": "Connection from 'Transform' to 'NonExistent' - target node not found"
}

2. Circular Dependencies

{
  "error": "Circular dependency detected: Node A → Node B → Node A"
}

3. Multiple Start Nodes

{
  "warning": "Multiple trigger nodes found - only one will execute"
}

4. Disconnected Nodes

{
  "warning": "Node 'Transform' is not connected to workflow flow"
}

Recovery Strategies

Strategy 1: Start Fresh

1. Note required fields from

   get_node

2. Create minimal valid configuration
3. Add features incrementally
4. Validate after each addition

Strategy 2: Binary Search

1. Remove half the nodes
2. Validate and test
3. If works: problem is in removed nodes
4. If fails: problem is in remaining nodes
5. Repeat until problem isolated

Strategy 3: Clean Stale Connections

n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{
    type: "cleanStaleConnections"
  }]
})

Strategy 4: Use Auto-fix

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

  runtime

  profile for pre-deployment
• Check

  valid

  field before assuming success
• Trust auto-sanitization for operator issues
• Use

  get_node

  when unclear about requirements
• Document false positives you accept

❌ Don't

• Skip validation before activation
• Try to fix all errors at once
• Ignore error messages
• Use

  strict

  profile during development (too noisy)
• Assume validation passed (always check result)
• Manually fix auto-sanitization issues
• Deploy with unresolved errors
• Ignore all warnings (some are important!)

Detailed Guides

• ERROR_CATALOG.md - Complete list of error types with examples
• FALSE_POSITIVES.md - When warnings are acceptable

Summary

1. Validation is iterative (avg 2-3 cycles, 23s + 58s)
2. Errors must be fixed, warnings are optional
3. Auto-sanitization fixes operator structures automatically
4. Use runtime profile for balanced validation
5. False positives exist - learn to recognize them
6. Read error messages - they contain fix guidance

1. Validate → Read errors → Fix → Validate again
2. Repeat until valid (usually 2-3 iterations)
3. Review warnings and decide if acceptable
4. Deploy with confidence

• n8n MCP Tools Expert - Use validation tools correctly
• n8n Expression Syntax - Fix expression errors
• n8n Node Configuration - Understand required fields