validates n8n workflow JSON the same way the n8n editor does on import. loads the actual n8n runtime packages (n8n-workflow + n8n-nodes-base), runs NodeHelpers.getNodeParameters() and getNodeParametersIssues() against every node. catches what JSON schema validation can't.

npx n8n-workflow-validator workflow.json

npm node license

• n8n-native validation — uses the same NodeHelpers functions the editor uses, not a custom schema
• structural checks — missing nodes/connections, bad types, invalid positions, missing parameters
• parameter-level checks — catches fixedCollection key mismatches, missing required fields, wrong typeVersion shapes
• LLM fixer — --fix auto-removes known bad patterns LLMs hallucinate (empty options: {} on if/switch nodes)
• sanitizer — regenerates node IDs, deduplicates webhook paths, auto-names unnamed nodes
• source locations — errors include line numbers, column offsets, and source snippets from your JSON
• flexible input — local file, remote URL, or stdin
• CI-friendly — --json for machine-readable output, exit code 0/1

npm install -g n8n-workflow-validator

or just run it:

npx n8n-workflow-validator workflow.json

from source:

git clone https://github.com/yigitkonur/n8n-workflow-validator.git
cd n8n-workflow-validator
pnpm install && pnpm build
node dist/cli.js workflow.json

requires Node.js 18+.

# validate a local file
n8n-validate workflow.json
# fix LLM-generated issues and write output
n8n-validate workflow.json --fix --out fixed.json
# validate from URL
n8n-validate "https://example.com/workflow.json"
# pipe from stdin, get JSON output
cat workflow.json | n8n-validate --json
# handle malformed JSON from LLMs
n8n-validate workflow.json --repair --accept-js-object
# skip sanitization
n8n-validate workflow.json --no-sanitize --no-regenerate-ids

USAGE:
 n8n-validate <file-or-url> [options]
OPTIONS:
 --fix auto-fix known LLM patterns (empty options on if/switch)
 --repair attempt to repair malformed JSON before parsing
 --accept-js-object accept JS object literal syntax (not strict JSON)
 --out <FILE> write fixed/sanitized workflow to file (only if valid)
 --json output machine-readable JSON instead of human-readable text
 --no-sanitize skip workflow sanitization
 --no-regenerate-ids skip UUID regeneration for node IDs
 -h, --help print usage

exit codes: 0 = valid, 1 = invalid or parse failure.

two layers of validation:

--fix currently applies one fixer:

• empty-options-if-switch — removes parameters.options: {} from if/switch nodes. LLMs love to hallucinate this. n8n throws "Could not find property option" because options is a fixedCollection and an empty object has no recognized keys.

two more fixers are available as library API only (not via CLI):

• switch-v3-rule-conditions-options — fills missing conditions.options with defaults on Switch v3+ nodes
• switch-v3-fallback-output-location — moves fallbackOutput from parameters.rules to parameters.options

import {
 jsonParse,
 validateWorkflowStructure,
 validateNodeWithN8n,
 nodeRegistry,
 fixInvalidOptionsFields,
 applyExperimentalFixes,
 sanitizeWorkflow,
 createSourceMap,
 findSourceLocation,
} from 'n8n-workflow-validator';

full TypeScript types exported.

src/
 cli.ts — entry point, arg parsing
 index.ts — library exports
 core/
 types.ts — all TypeScript interfaces
 validator.ts — structural validation
 n8n-native-validator.ts — wraps n8n NodeHelpers
 n8n-loader.ts — scans n8n-nodes-base, builds node registry
 fixer.ts — auto-fix rules
 sanitizer.ts — ID regen, name assignment, webhook dedup
 source-location.ts — JSON AST → line/col mapping, snippet extraction
 json-parser.ts — JSON / JS object / jsonrepair parsing
 utils/
 input-reader.ts — file / URL / stdin input handling
 output.ts — human-readable and JSON output formatting

1. reads input (file, URL, or stdin)
2. parses JSON (with optional repair or JS object mode)
3. applies fixers if --fix
4. runs structural checks on the raw object
5. for each node that passes structural checks: looks up its type in the n8n node registry (built by scanning the installed n8n-nodes-base package), then runs the same NodeHelpers validation the n8n editor uses
6. sanitizes the workflow (ID regen, name assignment, webhook dedup) unless --no-sanitize
7. outputs results and optionally writes the fixed workflow to disk

MIT