n8n Workflow Linter

n8n silently drops parameters it doesn't recognize. This linter tells you before your workflow breaks.

n8n Workflow Linter cover

What it does

Check n8n workflow JSON before you import it, share it or commit it. The linter compares every node against a snapshot of the real n8n node definitions (n8n-nodes-base and @n8n/n8n-nodes-langchain 2.46.7: 572 node types) and reports what n8n would silently drop or break.

Python 3.9+, no dependencies, offline. It never connects to your n8n instance.

python3 -m n8nlint check my-workflow.json        # or a folder of exports
python3 -m n8nlint check --strict workflows/     # warnings fail too (CI)
python3 -m n8nlint check --json workflows/       # machine-readable
python3 -m n8nlint creds my-workflow.json        # setup checklist: credentials + REPLACE_ME fields
python3 -m n8nlint info                          # which n8n version the snapshot covers

What you get

The screenshot is real output from the kit’s own commands. Tested from a fresh download of this exact zip: ./run_tests.sh ran 36 tests OK on Python 3.13 and 3.10.

Real terminal output from n8n Workflow Linter: demo and passing tests

What it catches

CodeProblem
E001 / E002not a workflow file, node missing name/type/typeVersion/position/parameters
E010 / E011duplicate node names or ids (connections and expressions resolve by name)
E020 / E022unknown node type, or a typeVersion that node does not have
E024a credential type the node does not accept
E030 / E031 / E033misspelled parameter, invalid option value, invalid collection option value
E040 / E042connections from or to nodes that no longer exist (renamed or deleted)
E041 / E043 / E044 / E045 / E046unknown connection type, output index the node does not have, AI connection from a node without that output, mismatched types, target without that input
E060hard-coded secrets: OpenAI/Anthropic keys, Shopify, Slack, GitHub, HubSpot, AWS, Stripe, Google keys, Bearer tokens
E091 / W090AI Agent, LLM Chain, Text Classifier or Information Extractor with no chat model connected; a Text Classifier prompt template missing {categories} (the model never sees your categories)
E080$('Node name') or $node["Node name"] expressions that point at a node that does not exist
W025hidden/deprecated nodes (Function, Function Item, Cron, Interval, ...)
W032unknown option inside a collection
W047 / W048 / W050disconnected nodes, nodes nothing runs, no trigger
W062pinData saved in the file (sample data can contain real customer data)
I021 / I023 / I061 / I063community nodes (not checked), older typeVersions, credential ids, active: true

Why it matters: n8n's parameter resolver (NodeHelpers.getNodeParameters in n8n-workflow) silently drops parameters it does not know, so a misspelled field in hand-written or AI-generated JSON just disappears and the node falls back to its default. We checked this against n8n-workflow itself; the test suite here covers each rule.

Try it

./demo.sh        # lints examples/: one clean workflow, one with 13 planted problems
./run_tests.sh   # 36 tests

Use it in CI (GitHub Actions)

- uses: actions/setup-python@v5
  with: { python-version: "3.12" }
- run: python3 -m n8nlint check --strict workflows/

Copy the n8nlint/ folder into your repo (or next to your workflows).

Use it with Claude Code

This folder is a Claude Code plugin with the n8n-workflow-linter skill. Claude lints any workflow it writes or edits and fixes errors before showing it to you.

Honest limits

  • A clean lint means the JSON matches the n8n node definitions. It does not prove the workflow does what you want; test it in n8n with sample data.
  • Parameter visibility rules (displayOptions) are not evaluated, so a parameter that exists for another operation of the same node is not flagged.
  • Options loaded from your account (channel lists, sheet names) and expressions are not checked.
  • Community nodes are listed but not checked. The snapshot is n8n 2.46.7; newer n8n versions may add node versions.

Format and license

Zip, 177 KB, v1.0, 14 files. Free to use, modify and share for any purpose, including commercial work, as long as this notice stays in copies. Not affiliated with or endorsed by n8n.

FAQ

Does it connect to my n8n?
No, it reads JSON files on your computer.
Which n8n version?
The snapshot is n8n-nodes-base and the LangChain nodes 2.46.7 (572 node types).
Does a clean lint mean my workflow works?
No, it means the JSON matches the node definitions; test with sample data.
How do I get the files?
Click Download free. The zip downloads straight away: no checkout, no account.
Do I have to sign up for the newsletter?
No. The form is optional and the download works without it.

Get n8n Workflow Linter

Free n8n workflow validator: catch unknown nodes, bad typeVersions, misspelled parameters, broken connections, renamed-node expressions and leaked API keys.

Save with a bundle

Pairs well with

Download$19

n8n Shopify Workflows Pack

5 importable n8n Shopify workflows: order alerts + Sheets log, low-stock alerts, review requests, daily sales summary, refund alerts. Tested. $19 once.

View n8n Shopify Workflows Pack
Download$19

n8n HubSpot Workflows Pack

4 importable n8n HubSpot workflows on CRM v3: lead capture with spam filter and routing, stale-deals report, weekly pipeline summary, new-contacts digest. $19.

View n8n HubSpot Workflows Pack
Download$19

n8n AI Agent Workflows Pack

4 importable n8n AI agent workflows: FAQ support agent, Gmail AI triage, AI lead qualification with rule-based scoring, feedback sentiment router. Tested. $19.

View n8n AI Agent Workflows Pack

Related