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.
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.
- Python >= 3.13
- uv package and project manager
uv tool install valn8nvaln8n check my_workflow.json
valn8n check --strict-only my_workflow.jsonSee also README in supplied demo workflows in demo_valn8n/broken_vs_notbroken.
valn8n check workflow.jsonvaln8n check workflows/Only check rules ND01xx and ND05xx.
valn8n check --select ND01,ND05 workflow.jsonIgnore ND05xx and ND0802.
valn8n check --ignore ND05,ND0802 workflow.jsonIgnore ND05xx but not ND0502.
valn8n check --ignore ND05 --extend-select ND0502 workflow.jsonRun only strict rules, skipping advisory and hint rules:
valn8n check --strict-only workflow.jsonvaln8n check --fmt json workflow.jsonvaln8n check -q workflow.jsonvaln8n check --tolerate-node-keys '*' workflow.jsonvaln8n rule| 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 |
| Code | Meaning |
|---|---|
| 0 | No violations found |
| 1 | Violations found |
| 2 | Error (e.g. file not found, invalid arguments) |
| 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.
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.