n8n-validation-expert

n8n Validation Expert

Expert guide for interpreting and fixing n8n validation errors.

---

Validation Philosophy

Validate early, validate often

Validation is typically iterative:

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

Key insight: Validation 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:

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

Doesn't block execution - Workflow can be activated but may have issues

Types:

• best_practice - Recommended but not required — surfaces under ai-friendly / strict only
• deprecated - Using old API/feature — surfaces under every profile
• security - Hardcoded secrets, unauthenticated webhooks — surfaces under every profile
• performance - Potential performance issue — advisory, ai-friendly / strict

Example (best-practice — appears under ai-friendly / strict):

{
  "type": "warning",
  "nodeName": "Slack",
  "message": "Slack API can have rate limits and transient failures"
}

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 Validation Loop

Pattern from Telemetry

7,841 occurrences of this pattern:

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

This is normal! Don't be discouraged by multiple iterations.

---

Validation Profiles

The four profiles are cumulative (n8n-mcp ≥ 2.63.0): each surfaces everything the lower one does, plus more. The dividing line is best-practice advisories — minimal and runtime withhold them; ai-friendly and strict add them. Errors are the same across every profile except that minimal skips a few config-level checks (e.g. enum validation of an explicit operation). Security and deprecation warnings surface under every profile.

minimal

Use when: Quick structural checks while wiring a workflow together.

Surfaces: hard errors that would stop execution (missing required fields, empty code, broken connections). Skips enum checks and all advisories.

Fastest and most permissive.

runtime (RECOMMENDED default)

Use when: Ongoing validation as you build; the everyday profile.

Surfaces: errors (required fields, value types, allowed values, dependencies, broken references) plus security and deprecation warnings. No best-practice advisories.

Balanced — catches everything that breaks, stays quiet about style.

ai-friendly

Use when: You want the best-practice advice before deploying.

Surfaces: everything runtime does, plus best-practice advisories — per-node "without error handling" suggestions, "webhook should always send a response", rate-limit notes, outdated-typeVersion suggestions, cachedResultName and long-chain hints.

Note: ai-friendly is stricter than runtime, not looser. (Older docs described it as reducing false positives — that was true only while profile gating was broken; it is fixed now.)

strict

Use when: Hardening a production-critical workflow.

Surfaces: everything ai-friendly does, plus leftover-property checks ("property 'X' won't be used — not visible with current settings").

Maximum lint. With the false positives fixed at the source, its warnings are advice to weigh, not noise to fight.

---

Common Error Types

Five core error types, in rough order of frequency:

• missing_required — a required field isn't provided. Use get_node to see required fields, then add it.
• invalid_value — value doesn't match allowed options (enums are case-sensitive). Check the error's allowed list or get_node.
• type_mismatch — wrong data type (string "100" vs number 100). Convert to the expected type.
• invalid_expression — expression syntax error (missing {{}}, typos). See the n8n Expression Syntax skill.
• invalid_reference — referenced node doesn't exist (renamed, deleted, or misspelled). Fix the name or cleanStaleConnections.

A sixth class, patchNodeField errors (find-not-found, ambiguous match, invalid/unsafe regex), surfaces when a patchNodeField op fails during n8n_update_partial_workflow — it's strict by design and errors rather than silently continuing.

Every type above has worked examples (broken config → fix) plus the patchNodeField error cases and their fixes in ERROR_CATALOG.md.

---

Auto-Sanitization System

Automatically normalizes common operator structures on ANY workflow update — n8n_create_workflow, n8n_update_partial_workflow, or any save. Trust it; don't hand-fix these.

What it normalizes on save:

• Binary operators (equals, notEquals, contains, notContains, greaterThan, lessThan, startsWith, endsWith) — removes a stray singleValue property.
• Unary operators (isEmpty, isNotEmpty, true, false) — adds singleValue: true.
• IF/Switch metadata — fills in conditions.options for IF v2.2+ and Switch v3.2+.

Validation no longer errors on these shapes (n8n-mcp ≥ 2.63.0). n8n derives unary-ness from the operator name and defaults the conditions.options sub-fields, so validate_node / validate_workflow accept a condition whether or not singleValue and the options metadata are present — the sanitizer just tidies the canonical form on save. (Older servers wrongly errored on the un-normalized shape; if you see that, upgrade.) What still is a real error: a v1-shaped conditions object on a v2 node, an empty filter with no conditions, and legacy v1 operator names (e.g. smaller) inside a v2 structure.

What the sanitizer CANNOT fix (handle manually): broken connections to non-existent nodes (use cleanStaleConnections), branch-count mismatches (add/remove connections or rules), and paradoxical corrupt states (may need manual DB intervention).

Before/after examples and the full cannot-fix detail are in ERROR_CATALOG.md (Auto-Sanitization sections).

---

False Positives

The validator overhaul (n8n-mcp ≥ 2.63.0) removed the classic false positives — template literals inside expressions, optional chaining, omitted-operation defaults, the Webhook → Respond-to-Webhook pattern, IF/Filter legacy shapes, and more no longer fire. There is no standing list of "known false positives to ignore."

What remains are best-practice advisories (surfaced only under ai-friendly / strict) that flag a real trade-off but may be acceptable in your case. Not every advisory needs a fix — many are context-dependent. Common ones and when each is acceptable vs. worth fixing:

• "...without error handling" — OK for dev/testing and non-critical notifications; fix for production handling important data. (Never a hard error — style doesn't block execution.)
• "No retry logic" — OK for idempotent ops, APIs with their own retry, manual triggers; fix for flaky external services and production automation.
• "...rate limits and transient failures" — OK for internal/low-volume/server-side-limited APIs; fix for public, high-volume APIs.
• "Unbounded query" — OK for small known datasets, aggregations, dev/testing; fix for production queries on large tables.

Security and deprecation warnings, by contrast, surface under every profile and should be treated as real.

Full per-case guidance, the list of what the validator no longer flags, profile strategies, the "should I fix this?" decision framework, and how to document accepted advisories are in FALSE_POSITIVES.md.

---

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 first — true means the config is valid; false means there are errors to fix before deployment.
2. Fix errors first — each carries

---

Content truncated.