valn8n

A validator for n8n workflow JSON files. Like ruff for Python, but for your n8n workflows.

Checks for errors, warning, and hints regarding syntax and semantics of workflows. Output in different formats (rich in terminal, text, JSON, CSV), most LLMs seem to work with 'text' quite well (tightly followed by JSON, but more tokens).

Also, valn8n allows me to asses the quality or hidden traps of workflows downloaded from the web, saving a lot of time not bothering with sometimes totally broken workflows.

Background

I have been testing n8n on and off with LLM assisted workflow generation and couldn't find a n8n workflow validator that would find whatever silly mistake an LLM (even flagship ones) could sometimes generate.

With valn8n however I can have the LLMs autocorrect those errors and am getting most n8n workflows as one-shot.

Requirements

• Python >= 3.13
• uv package and project manager

Installation

uv tool install valn8n

Quick Start

valn8n check my_workflow.json
valn8n check --strict-only my_workflow.json

See also README in supplied demo workflows in demo_valn8n/broken_vs_notbroken.

Usage

Check a single file

valn8n check workflow.json

Check a directory

valn8n check workflows/

Select specific rules

Only check rules ND01xx and ND05xx.

valn8n check --select ND01,ND05 workflow.json

Ignore specific rules

Ignore ND05xx and ND0802.

valn8n check --ignore ND05,ND0802 workflow.json

Switching back on ignored rules

Ignore ND05xx but not ND0502.

valn8n check --ignore ND05 --extend-select ND0502 workflow.json

Strict-only mode

Run only strict rules, skipping advisory and hint rules:

valn8n check --strict-only workflow.json

JSON output (for CI)

valn8n check --fmt json workflow.json

Quiet mode (summary only)

valn8n check -q workflow.json

Tolerate unknown node keys

valn8n check --tolerate-node-keys '*' workflow.json

List all rules

valn8n rule

Output Formats

Format	Flag	Description
Rich	--fmt rich	Colored terminal output (default)
Text	--fmt text	Plain text
JSON	--fmt json	Machine-readable JSON
CSV	--fmt csv	Comma-separated values
List	--fmt lst	One diagnostic per line

Exit Codes

Code	Meaning
0	No violations found
1	Violations found
2	Error (e.g. file not found, invalid arguments)

Rules

Group	Range	Description
IO	IO00xx	File I/O validation (read errors, invalid JSON)
ND01	ND01xx	Filter operations (invalid ops, common mistakes)
ND02	ND02xx	Node structure (unknown keys, value types, zero-property params)
ND03	ND03xx	Parameter validation (deep param keys, param value types)
ND04	ND04xx	Expression syntax (broken brackets, suspect prefixes)
ND05	ND05xx	Credential validation (missing, empty, placeholder, leaking)
ND06	ND06xx	Connection validation (unconnected inputs, dangling refs)
ND07	ND07xx	Error handling (missing errorWorkflow, unhandled errors)
ND08	ND08xx	Naming & documentation (default names, missing notes)

Rules ND01xx-ND04xx and ND06xx are strict (structural correctness). ND05xx and 07xx are advisory (best practices). ND08xx are hints (atm only regarding naming clarity and documentation).

Note: in future this may change and strict/advisory might not be clean ranges anymore.

Use --strict-only to run only strict rules.

Run valn8n rule to see the full list with descriptions.

Contributing

I do not accept PRs with code changes at the moment. But feel free to post issues (with full workflows attached) in case you think there is an error in valn8n, or if you see an opportunity to improve it.