“Your Node.js version is not supported by n8n” – fix for v20, v22, v23

Step by Step Guide for n8n Node Version Incompatibility

 

 

Who this is for: Developers and DevOps engineers who run n8n in production or CI environments and need a reliable, repeatable fix for “Unsupported Node.js version” errors. We cover this in detail in the n8n Installation Errors Guide

---

Quick Diagnosis

1. Check the active Node version

   node -v

2. Switch to a supported LTS with nvm

   nvm install 18   # or 16 / 14
   nvm use 18

3. Re‑install n8n in the same shell

   npm install -g n8n
   n8n start

4. Confirm both versions

   node -v && n8n --version

Result: n8n launches without version‑compatibility errors.

---

1. Why Node.js Version Matters for n8n

If you encounter any permission denied error n8n resolve them before continuing with the setup.

Micro‑summary: n8n’s core libraries are compiled against specific Node ABIs; using an unsupported runtime leads to module‑resolution failures.

n8n version	Minimum Node	Recommended Node	End‑of‑Life (EOL)
0.230 – latest	14.15	16.x or 18.x	14 → Apr 2023, 16 → Sep 2023, 18 → Apr 2025
0.150 – 0.229	12.22	14.x	12 → Apr 2022

EEFA note: Running a Node version past its EOL exposes you to unpatched security vulnerabilities and can cause silent crashes in production.

---

2. Detecting the Current Node.js Version

If you encounter any missing environment variables n8n resolve them before continuing with the setup.

Micro‑summary: Verify the runtime before any install or upgrade.

Run the following command to print the active Node version:

node -v   # e.g. v12.22.9

If the output falls outside the supported range, you’ll see an error such as:

Error: n8n requires Node.js version >=14.15.0 <20.0.0

---

3. Installing a Compatible Node.js Version with nvm

3.1 Install nvm (Node Version Manager)

Micro‑summary: nvm isolates Node versions per user, preventing accidental upgrades that break other services.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

Windows (PowerShell 5+)

Invoke-WebRequest -Uri https://raw.githubusercontent.com/coreybutler/nvm-windows/master/install.ps1 -OutFile install.ps1
.\install.ps1

EEFA: On production servers, prefer the *system‑wide* package manager only if you cannot use nvm. nvm keeps Node versions scoped to the user account.

3.2 List Available LTS Versions

nvm ls-remote | grep -E 'v(14|16|18)\.'

3.3 Install & Activate a Supported Version

# Install the latest LTS (currently 18.x)
nvm install 18
# Switch to it for the current session
nvm use 18
# Make it the default for new shells
nvm alias default 18

Verification

node -v   # → v18.19.0 (example)
npm -v    # → 10.2.3

---

4. Re‑installing n8n After Switching Node Versions

Micro‑summary: A clean reinstall removes binaries compiled for the old ABI.

4.1 Global Installation (quick start)

npm uninstall -g n8n
npm install -g n8n
n8n start

4.2 Local Installation (recommended for CI/CD)

mkdir ~/n8n && cd ~/n8n
npm init -y
npm install n8n
npx n8n start

---

5. Common Node‑Version‑Related Failure Scenarios

Symptom	Likely Cause	Fix
npm ERR! unsupported engine	package.json requires >=14 <20 but active Node is 12	Switch Node via nvm use 16
Error: Cannot find module ‘node:fs’	Running Node < 16 (module namespace added in v16)	Upgrade to Node 16+
ERR_REQUIRE_ESM during npm install	Old Node cannot parse ES modules used by recent n8n deps	Upgrade Node or install older n8n (npm i -g n8n@0.200)
Segmentation fault (core dumped) after npm install	Binary addons compiled for a different ABI	Re‑install after nvm use <compatible>; delete node_modules first

Troubleshooting checklist

• node -v is within the supported range.
• npm config get prefix points to the same user directory as nvm.
• No stray node_modules from a previous version (rm -rf $(npm root -g)/n8n).
• Environment variable NODE_OPTIONS is cleared (it can force unsupported flags).

---

6. Verifying a Successful Installation

Micro‑summary: Confirm both the server and the API health endpoints report the correct runtime.

6.1 Start n8n with a tunnel (optional)

n8n start --tunnel

You should see a snippet like:

n8n ready on http://localhost:5678
Version: 0.230.0
Node: v18.19.0

6.2 Query the health endpoint

curl -s http://localhost:5678/api/health | jq .

Expected JSON:

{
  "status": "ok",
  "version": "0.230.0",
  "nodeVersion": "v18.19.0"
}

---

7. When nvm Is Not an Option (Docker, CI, or System‑wide Node)

Micro‑summary: Choose the environment‑specific method that guarantees the correct Node ABI without relying on nvm.

Environment	Recommended Approach
Docker	Use the official image tagged with the desired Node version, e.g. n8nio/n8n:0.230-node18.
CI/CD (GitHub Actions, GitLab)	Add actions/setup-node@v4 with node-version: 18 before npm install.
System‑wide (apt, yum)	Pin the package to a supported LTS (apt-get install nodejs=18.*) and lock it with apt-mark hold nodejs.

EEFA: In containerised environments, never rely on nvm inside the container; base the image on the correct Node LTS instead.

---

8. FAQ

• Q: Can I run n8n on Node 20?
  A: Not yet. n8n’s dependencies have not been upgraded to the Node 20 ABI. Attempting to do so results in “Unsupported Node.js version” errors. Wait for the next major n8n release.
• Q: I’m on Windows and nvm fails to install. What now?
  A: Use nvm‑windows (a separate project) or download the official Node.js MSI for the LTS version, then reinstall n8n. See the *Windows installation guide* child page for step‑by‑step instructions.
• Q: Does npm ci help?
  A: Yes. After switching to a compatible Node version, npm ci performs a clean install based on package-lock.json, eliminating leftover binaries from a previous Node version.

---

Conclusion

Running n8n on a supported Node LTS (14, 16, or 18) is non‑negotiable for production stability. By verifying the runtime, using nvm to manage isolated Node versions, and reinstalling n8n after any switch, you eliminate ABI mismatches that cause “Unsupported Node.js version” errors. The same principles apply in Docker, CI/CD, and system‑wide installations—use the appropriate Node LTS image or package manager and lock the version. Following these steps ensures a secure, reliable n8n deployment that aligns with real‑world production constraints.