🔍 n8n-workflow-validator 🔍

Stop praying your workflow JSON is valid. Start getting real answers.

The CLI + library that validates n8n workflows using n8n's actual engine. It tells you exactly what's wrong, shows the correct schema, and auto-fixes common mistakes.

  •  

🧭 Quick Navigation

⚡ Get Started • ✨ Key Features • 🎮 CLI Usage • 📦 API Reference • 🆚 Why This Exists

---

n8n-workflow-validator is the validation layer your n8n tooling deserves. Building an MCP server? A workflow generator? An AI agent that creates automations? This tool uses n8n's actual validation engine (n8n-workflow + n8n-nodes-base) to give you the exact same errors you'd see in the n8n editor—plus schema hints that show exactly how to fix them.

⚙️ Native n8n Engine Uses actual n8n-workflow

🎯 Schema Delta Detection Shows missing/extra keys

🔧 Auto-Fix Mode Repairs common issues

🤖 LLM-Friendly Output JSON with schema hints

How it slaps:

• You: LLM generates a workflow. Is it valid?
• Old way: Paste into n8n. Get "Could not find property option". Cry.
• Validator way: npx n8n-workflow-validator workflow.json
• Result: Line numbers. Schema diff. Correct usage example. Fix and ship.

---

💥 Why This Exists

LLMs generate n8n workflows. Workflows have complex schemas. Validation errors are cryptic. This tool fixes all of that.

❌ The Old Way (Pain)	✅ The Validator Way (Glory)
LLM generates workflow JSON. Paste into n8n editor. Get cryptic error: "Could not find property" Hunt through n8n docs for schema. Manually fix. Repeat 10 times.	LLM generates workflow JSON. npx n8n-workflow-validator --json Get exact schema diff + correct example. --fix auto-repairs common issues. Ship with confidence. ☕

We use actual n8n packages (n8n-workflow, n8n-nodes-base) to validate. Same engine as the n8n editor. Zero guesswork.

---

🚀 Get Started in 10 Seconds

# Validate any workflow JSON
npx n8n-workflow-validator workflow.json

# Auto-fix and save
npx n8n-workflow-validator workflow.json --fix --out fixed.json

# JSON output for LLMs/automation
npx n8n-workflow-validator workflow.json --json

No config. No setup. Just works.

---

✨ Feature Breakdown: The Secret Sauce

Feature	What It Does	Why You Care
⚙️ Native Engine n8n-workflow + n8n-nodes-base	Uses NodeHelpers.getNodeParameters from n8n	Same validation as n8n editor—identical errors
🎯 Schema Delta Missing/extra key detection	Shows exactly which keys are wrong vs schema	Fix the right thing the first time
📍 Source Locations Line & column numbers	Points to exact JSON location with code snippet	No hunting through 1000-line files
💡 Correct Usage Schema-derived examples	Shows the correct parameter structure	Copy-paste the fix, done
🔧 Auto-Fix --fix flag	Repairs Switch v3 conditions, fallbackOutput, etc.	Let the tool do the boring work
🤖 JSON Output --json flag	Structured output with all schema hints	Perfect for LLMs and CI pipelines

---

🎮 CLI Usage

Basic Validation

npx n8n-workflow-validator workflow.json

Rich Error Output

❌ INVALID: workflow.json
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🛑 ERRORS (1)

────────────────────────────────────────────────────────────────────────────────
[1] N8N_PARAMETER_VALIDATION_ERROR
    Path: nodes[12]
    Location: Line 305, Column 5
    Node: "route-by-format" (n8n-nodes-base.switch)

    Message: Could not find property option

    Source:
    ┌──────┬────────────────────────────────────────────────────────────
    │ 302 │          "typeVersion": 2,
    │ 303 │          "onError": "continueErrorOutput"
    │ 304 │        },
    │ 305 │>>>     {
    │ 306 │          "parameters": {
    └──────┴────────────────────────────────────────────────────────────

    Root Cause Analysis:
      • n8n Runtime Error: "Could not find property option"

    Schema Delta:
      • Missing keys: options
      • Extra keys: fallbackOutput

    Correct Usage:
    ┌──────────────────────────────────────────────────────────────────
    │ {
    │   "conditions": {
    │     "options": {
    │       "caseSensitive": true,
    │       "leftValue": "",
    │       "typeValidation": "strict"
    │     },
    │     "conditions": [...],
    │     "combinator": "and"
    │   }
    │ }
    └──────────────────────────────────────────────────────────────────

---

JSON Output for LLMs & Automation

npx n8n-workflow-validator workflow.json --json

Returns structured data with schema hints for programmatic consumption:

{
  "valid": false,
  "issues": [{
    "code": "N8N_PARAMETER_VALIDATION_ERROR",
    "severity": "error",
    "message": "Could not find property option",
    "location": {
      "nodeName": "route-by-format",
      "nodeType": "n8n-nodes-base.switch",
      "path": "nodes[12]"
    },
    "sourceLocation": { "line": 305, "column": 5 },
    "context": {
      "n8nError": "Could not find property option",
      "fullObject": { "mode": "rules", "rules": {} },
      "expectedSchema": { "mode": "rules", "rules": {}, "options": {} },
      "schemaPath": "parameters"
    }
  }]
}

Perfect for feeding back into an LLM to auto-correct workflows.

---

CLI Options

Option	Description
--fix	Auto-fix known issues (Switch v3, fallbackOutput, etc.)
--json	JSON output for programmatic use
--out FILE	Write fixed workflow to FILE
--repair	Repair malformed JSON before validation
--no-sanitize	Skip sanitization step
-h, --help	Show help

---

Exit Codes

Code	Meaning
0	✅ Valid workflow
1	❌ Invalid workflow

---

📦 API Usage

Use as a library in your own tools:

import { 
  validateWorkflowStructure, 
  validateNodeWithN8n,
  nodeRegistry,
  jsonParse 
} from 'n8n-workflow-validator';

const raw = fs.readFileSync('workflow.json', 'utf8');
const workflow = jsonParse(raw);
const result = validateWorkflowStructure(workflow, { rawSource: raw });

for (const issue of result.issues) {
  console.log(`[${issue.code}] ${issue.message}`);
  
  // Schema hints for LLMs
  if (issue.context?.expectedSchema) {
    console.log('Expected:', JSON.stringify(issue.context.expectedSchema, null, 2));
  }
  
  // Delta detection
  if (issue.context?.schemaDelta) {
    console.log('Missing:', issue.context.schemaDelta.missingKeys);
    console.log('Extra:', issue.context.schemaDelta.extraKeys);
  }
}

---

🎯 What Gets Validated

Layer	What's Checked	Source
Structure	nodes array, connections object, required fields	JSON schema
Parameters	All node parameters against schema	NodeHelpers.getNodeParameters
Connections	Valid node references, input/output types	n8n connection rules
Node Types	Known types from n8n-nodes-base	Node registry
Auto-Fix Targets	Switch v3 conditions, fallbackOutput location	Common LLM mistakes

---

🔧 Installation Options

# Use directly with npx (no install needed)
npx n8n-workflow-validator workflow.json

# Or install globally
npm install -g n8n-workflow-validator
n8n-validate workflow.json

# Or add to your project
npm install n8n-workflow-validator

---

🎯 Use Cases

Scenario	How This Helps
🤖 MCP Servers	Validate before sending to n8n API
🧠 LLM Agents	Get schema hints to fix generated workflows
🔧 Workflow Generators	Ensure output is valid before export
🧪 CI/CD Pipelines	Block invalid workflows in PRs
📥 Import Tools	Pre-validate user uploads
🔄 Migration Tools	Validate during version upgrades

---

🔥 Common Issues & Quick Fixes

Expand for troubleshooting tips

Problem	Solution
"Could not find property"	Check Schema Delta in output—shows missing/extra keys
Switch node errors	Use --fix flag—auto-fixes Switch v3 condition structure
Malformed JSON	Use --repair flag to fix common JSON syntax errors
Too many errors	Fix structure errors first (missing nodes/connections)
Node type not found	Ensure node type exists in current n8n-nodes-base version

---

🛠️ Development

# Clone
git clone https://github.com/yigitkonur/n8n-workflow-validator.git
cd n8n-workflow-validator

# Install
npm install

# Build
npm run build

# Test
npm test

---

Built with 🔥 because "Could not find property option" is not helpful.

MIT © Yiğit Konur