Validation Expert

Expert guide for interpreting and fixing n8n validation errors.

Validate early, validate often. Validation is iterative — expect 2–3 validate → fix cycles. The average is 23 seconds thinking about errors and 58 seconds fixing them per cycle.

The Validation Loop

From real telemetry: 7,841 occurrences of this exact pattern:

1. Configure node
   ↓
2. validate_node  (23s thinking about errors)
   ↓
3. Read error messages carefully
   ↓
4. Fix errors
   ↓
5. validate_node again  (58s fixing)
   ↓
6. Repeat until valid  (usually 2–3 iterations)

Example Loop

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

Multiple validation iterations are completely normal. Don’t try to fix all errors at once — address them one at a time.

Validation Profiles

Choose the right profile for your development stage:

minimal
runtime (recommended)
ai-friendly
strict

Use when: Quick checks during active editingValidates: Required fields only, basic structurePros: Fastest, most permissiveCons: May miss real issues

validate_node({
  nodeType: "nodes-base.slack",
  config: {},
  mode: "minimal"
})
// Returns: missingRequiredFields array

Use when: Pre-deployment validationValidates: Required fields, value types, allowed values, basic dependenciesPros: Balanced — catches real errors without excessive noiseCons: Some edge cases missed

validate_node({
  nodeType: "nodes-base.slack",
  config: {resource: "message", operation: "post", channel: "#general", text: "Hello!"},
  profile: "runtime"
})

Use when: AI-generated node configurationsValidates: Same as runtime but reduces false positivesPros: Less noisy for AI workflows

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

Use when: Final check before critical production deploymentValidates: Everything — best practices, performance, securityPros: Maximum safetyCons: Many warnings; some false positives; not recommended during development

validate_node({
  nodeType: "nodes-base.slack",
  config: {...},
  profile: "strict"
})

Validation Result Structure

{
  "valid": false,
  "errors": [
    {
      "type": "missing_required",
      "property": "channel",
      "message": "Channel name is required",
      "fix": "Provide a channel name (lowercase, no spaces, 1-80 characters)"
    }
  ],
  "warnings": [
    {
      "type": "best_practice",
      "property": "errorHandling",
      "message": "Slack API can have rate limits",
      "suggestion": "Add onError: 'continueRegularOutput' with retryOnFail"
    }
  ],
  "suggestions": [
    {
      "type": "optimization",
      "message": "Consider using batch operations for multiple messages"
    }
  ],
  "summary": {
    "hasErrors": true,
    "errorCount": 1,
    "warningCount": 1,
    "suggestionCount": 1
  }
}

Error Severity Levels

Severity	Blocks Execution?	Action Required
Error	Yes — must fix before activation	Fix immediately
Warning	No — workflow can run but may have issues	Fix for production
Suggestion	No — optional improvement	Fix if convenient

Common Error Catalog

missing_required — Required field not provided

What it means: A field that is required for the selected operation is absent.How to fix:

Use get_node to see what fields the operation requires
Add the missing field with an appropriate value

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

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

invalid_value — Value not in allowed options

What it means: The value provided doesn’t match the list of allowed options.How to fix:

Read the error message for the allowed values list
Use get_node to see all options

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

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

type_mismatch — Wrong data type

What it means: The value is the right field but the wrong type (e.g., string instead of number).

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

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

invalid_expression — Expression syntax error

What it means: An expression field has invalid {{}} syntax.

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

// Fix — add {{}} wrapper
config.text = "={{$json.name}}";

See the Expression Syntax skill for the full expression guide.

invalid_reference — Referenced node doesn't exist

What it means: An expression references a node that doesn’t exist in the workflow.

// Error
{
  "type": "invalid_reference",
  "property": "expression",
  "message": "Node 'HTTP Requets' does not exist",
  "current": "={{$node['HTTP Requets'].json.data}}"
}

// Fix — correct the typo
config.expression = "={{$node['HTTP Request'].json.data}}";

Auto-Sanitization System

Auto-sanitization runs automatically on ALL nodes during ANY workflow update (create or update_partial).

What It Fixes Automatically

Binary Operators
Unary Operators
IF / Switch Metadata

Operators that compare two values: equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWithFix: Removes singleValue property (binary operators should not have it)

// Before (wrong)
{
  "type": "boolean",
  "operation": "equals",
  "singleValue": true   // ❌ Binary operators don't need this
}

// After (auto-fixed)
{
  "type": "boolean",
  "operation": "equals"
  // singleValue removed ✅
}

Operators that check a single value: isEmpty, isNotEmpty, true, falseFix: Adds singleValue: true (unary operators require it)

// Before (wrong)
{
  "type": "boolean",
  "operation": "isEmpty"
  // Missing singleValue ❌
}

// After (auto-fixed)
{
  "type": "boolean",
  "operation": "isEmpty",
  "singleValue": true   // ✅ Added automatically
}

Fix: Adds complete conditions.options metadata for:

IF node v2.2+
Switch node v3.2+

This happens automatically on save — no manual intervention needed.

What Auto-Sanitization Cannot Fix

Issue	Cause	Solution
Broken connections	References to deleted nodes	Use `cleanStaleConnections` operation
Branch count mismatches	3 Switch rules but only 2 connections	Add missing connections or remove rules
Paradoxical corrupt states	API returns corrupt, rejects updates	May require manual database intervention

Auto-Fix Tool

For bulk fixes beyond auto-sanitization:

// Preview fixes first (default: doesn't apply)
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: false,
  confidenceThreshold: "medium"  // high, medium, low
})

// Apply fixes after review
n8n_autofix_workflow({
  id: "workflow-id",
  applyFixes: true
})

Fix types the auto-fix tool handles:

expression-format — Fix expression syntax
typeversion-correction — Correct typeVersion
error-output-config — Fix error output settings
webhook-missing-path — Add missing webhook paths
typeversion-upgrade — Upgrade to latest version
version-migration — Apply version migrations

False Positives Guide

Some validation warnings are technically “wrong” but acceptable in context.

Missing error handling

When it’s a false positive: Simple workflows where failures are obvious, testing or development workflows, and non-critical notification workflows.When you should fix it: Production workflows handling important data or payments.

No retry logic

When it’s a false positive: APIs with their own built-in retry logic, idempotent operations where double-execution is harmless, and manual trigger workflows run by a human.When you should fix it: Flaky external services in production automation.

Missing rate limiting

When it’s a false positive: Internal APIs with no rate limits, low-volume workflows (few executions per day), and APIs that enforce rate limiting server-side.When you should fix it: Public APIs with strict rate limits and high-volume automated workflows.

Unbounded query

When it’s a false positive: Small, known-size datasets, aggregation queries (COUNT, SUM) that scan the full table by design, and development/testing environments.When you should fix it: Production queries on large tables.

To reduce false positives in AI-generated configurations:

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

Workflow Validation

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

// Validate by workflow ID (requires n8n API)
n8n_validate_workflow({
  id: "workflow-id",
  options: {profile: "runtime"}
})

Common Workflow-Level Errors

Error	Cause	Fix
`Connection from 'X' to 'Y' - target node not found`	Stale connection to a deleted node	Use `cleanStaleConnections` operation
`Circular dependency detected: A → B → A`	Loop in workflow	Restructure to remove the cycle
`Multiple trigger nodes found`	More than one trigger	Remove extra triggers or split into separate workflows
`Node 'X' is not connected to workflow flow`	Orphaned node	Connect it or delete it

Recovery Strategies

Start Fresh
Clean Stale Connections
Auto-Fix
Binary Search

When: Configuration is severely broken or corrupted.

// 1. Get required fields
get_node({nodeType: "nodes-base.slack", mode: "minimal"})

// 2. Create minimal valid config
const config = {resource: "message", operation: "post", channel: "#general", text: "Hi"};

// 3. Validate
validate_node({nodeType: "nodes-base.slack", config, profile: "runtime"})

// 4. Add features incrementally, validating after each addition

When: Seeing “Node not found” or broken connection errors.

n8n_update_partial_workflow({
  id: "workflow-id",
  intent: "Clean up stale connections after node deletions",
  operations: [{type: "cleanStaleConnections"}]
})

When: Operator structure errors (isEmpty missing singleValue, etc.).

// Preview first
n8n_autofix_workflow({id: "workflow-id", applyFixes: false})

// Apply after review
n8n_autofix_workflow({id: "workflow-id", applyFixes: true})

Profile Selection by Stage

Development Stage	Recommended Profile
Initial editing / exploration	`minimal`
Active development	`runtime`
AI-generated configs	`ai-friendly`
Pre-deployment check	`runtime`
Critical production deployment	`strict`

Best Practices

Do

Validate after every significant change
Read error messages completely before fixing
Fix errors one at a time iteratively
Check the valid field — don’t assume it passed
Trust auto-sanitization for operator issues
Use get_node when the required fields aren’t obvious

Don't

Skip validation before activation
Try to fix all errors simultaneously
Use strict profile during development
Manually fix auto-sanitization issues
Deploy with unresolved error severity issues
Ignore all warnings (some are genuinely important)

Get Started

Skills

Guides

Development

Validation Expert

Validation Expert

The Validation Loop

Example Loop

Validation Profiles

Validation Result Structure

Error Severity Levels

Common Error Catalog

Auto-Sanitization System

What It Fixes Automatically

What Auto-Sanitization Cannot Fix

Auto-Fix Tool

False Positives Guide

Workflow Validation

Common Workflow-Level Errors

Recovery Strategies

Profile Selection by Stage

Best Practices

Do

Don't

Build docs developers (and LLMs) love

Get Started

Skills

Guides

Development

Documentation Index

​Validation Expert

​The Validation Loop

​Example Loop

​Validation Profiles

​Validation Result Structure

​Error Severity Levels

​Common Error Catalog

​Auto-Sanitization System

​What It Fixes Automatically

​What Auto-Sanitization Cannot Fix

​Auto-Fix Tool

​False Positives Guide

​Workflow Validation

​Common Workflow-Level Errors

​Recovery Strategies

​Profile Selection by Stage

​Best Practices

Do

Don't

Build docs developers (and LLMs) love

Validation Expert

The Validation Loop

Example Loop

Validation Profiles

Validation Result Structure

Error Severity Levels

Common Error Catalog

Auto-Sanitization System

What It Fixes Automatically

What Auto-Sanitization Cannot Fix

Auto-Fix Tool

False Positives Guide

Workflow Validation

Common Workflow-Level Errors

Recovery Strategies

Profile Selection by Stage

Best Practices