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.
⚠️ 2025‑2026 Version Update: Read This First
n8n’s supported Node.js range changed significantly in 2025. If your bookmarks, tutorials, or older guides tell you to use Node 14, 16, or 18 – they are now out of date. n8n 1.x (from mid‑2025) and n8n 2.x dropped support for Node 18 entirely. The current official requirement is:
| n8n version range | Minimum Node.js | Maximum Node.js | Recommended |
|---|---|---|---|
| n8n 2.x (current, Dec 2025+) | 20.19 | 24.x | Node 20 LTS or Node 22 LTS |
| n8n 1.x (late 2024 – late 2025) | 18.17 | 22.x | Node 18 LTS or Node 20 LTS |
| n8n 0.230 – 1.x (early 2024) | 14.15 | 18.x | Node 16 or 18 LTS |
EEFA note: Node 18 reached End‑of‑Life in April 2025. Node 25 (unstable/odd major) is explicitly not supported — its ABI (141) is incompatible with the isolated‑vm native module n8n uses for Code node sandboxing. Always use an even‑numbered LTS release.
Quick Diagnosis
- Check the active Node version
node -v
- Switch to a supported LTS with nvm
nvm install 20 # Node 20 LTS — safest choice for n8n in 2025-2026 nvm use 20
- Re‑install n8n in the same shell
npm install -g n8n n8n start
- 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 and crash‑loops.
n8n bundles native C++ addons — most critically isolated‑vm (used for Code node sandboxing) and sqlite3 — that are compiled for a specific Node.js Application Binary Interface (ABI). Each major Node.js version has a unique ABI number. When the ABI the binary was compiled for does not match the runtime ABI, Node.js refuses to load it and throws either an “Unsupported Node.js version” message or an ABI mismatch error like:
Error: No native build was found for platform=linux arch=x64 runtime=node abi=141 uv=1 libc=glibc node=25.8.1 loaded from: /usr/lib/node_modules/n8n/node_modules/isolated-vm
| n8n version | Minimum Node | Recommended Node | EOL / status |
|---|---|---|---|
| n8n 2.x (current) | 20.19 | 20 LTS or 22 LTS | Node 20 active LTS until Apr 2026; Node 22 until Apr 2027 |
| n8n 1.x | 18.17 | 18 or 20 LTS | Node 18 EOL Apr 2025 — no longer supported |
| n8n 0.230 – early 1.x | 14.15 | 16 or 18 LTS | Node 14 EOL Apr 2023; Node 16 EOL Sep 2023 |
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. v20.19.1
If the output falls outside the supported range, you’ll see an error such as:
# Too old (e.g. Node 18 with n8n 2.x) npm ERR! engine Unsupported engine npm ERR! engine Not compatible with your version of node: expected ">=20.19 <25", got "18.20.0" # Too new (e.g. Node 25 with any current n8n) Your Node.js version 25.8.1 is currently not supported by n8n. Please use Node.js v20 or v22 instead. # PaaS deployments picking latest Node automatically Your Node.js version 23.0.0 is currently not supported by n8n. Please use Node.js v18.17.0 (recommended), v20, or v22 instead!
Check which Node version nvm currently reports as active:
nvm current # shows the active nvm-managed version nvm ls # lists all installed versions and marks the active one which node # verifies the binary path nvm is using
EEFA: On servers with both a system Node and nvm‑managed Node, nvm current and node ‑v can disagree if nvm wasn’t sourced in the current shell. Always run which node to confirm which binary is actually being invoked.
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 # Then reload your shell profile source ~/.bashrc # or ~/.zshrc on macOS
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, preventing global version changes from breaking other services.
3.2 List Available LTS Versions
nvm ls-remote | grep -E 'v(20|22|24)\.'
3.3 Install & Activate a Supported Version
# Install Node 20 LTS (recommended for n8n 2.x in 2025-2026) nvm install 20 # Switch to it for the current session nvm use 20 # Make it the default for new shells nvm alias default 20
Verification
node -v # → v20.19.1 (or higher within the 20.x series) npm -v # → 10.x.x
3.4 Lock the Version with .nvmrc (Prevents Future Breakage)
The most common cause of recurrence is a Node upgrade that silently moves the version outside n8n’s supported range. Locking it in a .nvmrc file prevents this in every environment — local, CI, and production.
# In your n8n project root (or home directory for global installs) echo "20" > .nvmrc # Verify — nvm will now automatically use this version in this directory nvm use # reads .nvmrc, no argument needed
Auto‑switch on directory entry (optional, macOS/Linux): Add this to your ~/.zshrc or ~/.bashrc:
autoload -U add-zsh-hook
load-nvmrc() {
local nvmrc_path="$(nvm_find_nvmrc)"
if [ -n "$nvmrc_path" ]; then
local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")")
if [ "$nvmrc_node_version" != "$(nvm version)" ]; then
nvm use
fi
fi
}
add-zsh-hook chpwd load-nvmrc
load-nvmrc
EEFA: Pair the .nvmrc with a package.json "engines" field as a second enforcement layer:
{
"engines": {
"node": ">=20.19 <25"
}
}
4. Re‑installing n8n After Switching Node Versions
Micro‑summary: A clean reinstall removes binaries compiled for the old ABI. Never skip this step — stale native modules are the #1 source of post‑switch errors.
4.1 Global Installation (quick start)
npm uninstall -g n8n npm cache clean --force 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
4.3 When You’ve Already Switched Node but n8n Still Errors?
If you switched Node versions but didn’t reinstall n8n, native modules are still compiled for the old ABI. The fix is a forced clean rebuild:
# Remove all stale n8n binaries rm -rf $(npm root -g)/n8n npm cache clean --force # Reinstall fresh against the new Node ABI npm install -g n8n
EEFA: On memory‑constrained VPS instances (under 1 GB RAM), npm install ‑g n8n can fail silently during native module compilation due to out‑of‑memory conditions. If the install completes but n8n won’t start, add a swap file or use the pre‑built Docker image instead.
5. Common Node‑Version‑Related Failure Scenarios
| Symptom / Error | Likely Cause | Fix |
|---|---|---|
npm ERR! unsupported engine |
Active Node is outside n8n’s engines range |
Switch Node via nvm use 20 |
Error: Cannot find module 'node:fs' |
Running Node < 16 (module namespace added in v16) | Upgrade to Node 20+ |
ERR_REQUIRE_ESM during install |
Old Node cannot parse ES modules in recent n8n deps | Upgrade Node to 20+ |
No native build was found for ... abi=141 |
Node 25 (odd/unstable) — ABI not supported by isolated‑vm |
Downgrade to Node 24 LTS or Node 22 LTS |
| Segmentation fault after install | Binary addons compiled for a different ABI | Delete node_modules and reinstall after switching Node |
Your Node.js version X is not supported on PaaS |
PaaS (Railway, Render, Heroku) auto‑selects latest Node (23+) | Pin Node version via platform env var (see Section 7) |
| Code node crash‑loops after n8n 2.8.x upgrade | External task runner image not updated with Node 24 support | Pull latest n8nio/runners image; stay on n8n 2.7.x until runners image is fixed |
Troubleshooting checklist
node ‑vis within the supported range (20.19–24.x for n8n 2.x).npm config get prefixpoints to the same user directory as nvm.- No stale
node_modulesfrom a previous version (rm ‑rf $(npm root ‑g)/n8n). - Environment variable
NODE_OPTIONSis cleared (it can force unsupported flags). - On Apple Silicon:
node ‑e "console.log(process.arch)"returnsarm64notx64.
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: 2.x.x Node: v20.19.1
6.2 Query the health endpoint
curl -s http://localhost:5678/healthz | jq .
Expected JSON:
{
"status": "ok"
}
EEFA: The /healthz/readiness endpoint additionally checks database and Redis connectivity. Use this in Kubernetes liveness/readiness probes rather than the base /healthz endpoint to get a complete health signal.
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: docker.n8n.io/n8nio/n8n:latest or pin a specific version tag. Node is baked in at the correct version. |
| GitHub Actions | Use actions/setup‑node@v4 with node‑version: '20' or node‑version‑file: '.nvmrc'. |
| Railway | Set NIXPACKS_NODE_VERSION=20 in Railway environment variables. |
| Render | Add NODE_VERSION=20 as an environment variable in the Render dashboard. |
| Heroku | Add "engines": {"node": "20.x"} to your package.json. Heroku reads this field at build time. |
| System‑wide (apt, yum) | Pin with apt-get install nodejs=20.* and lock 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.
7a. Docker‑Specific Fix: Pinning Node Version in Your Image
The most reliable way to guarantee the correct Node version in Docker is to use the official n8n image, which bundles a supported Node runtime. Never use node:latest as the base image for a custom n8n Dockerfile — :latest currently resolves to Node 24+ and may move to Node 25 or 26 without warning.
# Option 1: Use the official n8n image (recommended) docker run -it --rm \ -p 5678:5678 \ -v n8n_data:/home/node/.n8n \ docker.n8n.io/n8nio/n8n:2.14.2 # pin exact version — never use :latest in production # Option 2: Build a custom image pinned to Node 20 FROM node:20-bullseye RUN npm install -g n8n@2.14.2 # pin n8n version too EXPOSE 5678 CMD ["n8n", "start"]
Docker Compose example with pinned versions:
services:
n8n:
image: docker.n8n.io/n8nio/n8n:2.14.2 # pin — never use :latest
restart: unless-stopped
ports:
- "5678:5678"
volumes:
- n8n_data:/home/node/.n8n
volumes:
n8n_data:
EEFA: Prefer node:20-bullseye over node:20-alpine for custom Dockerfiles. Alpine’s musl libc can cause node‑gyp compilation failures for native modules like isolated‑vm and sqlite3. If you must use Alpine, install musl‑dev and python3 before running npm install.
7b. CI/CD Fix: GitHub Actions, GitLab & Others
CI pipelines that don’t pin the Node version will eventually break as the default runtime upgrades. Here are complete, copy‑paste configurations for the most common CI platforms.
GitHub Actions
name: n8n CI
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# Option A: pin by major version
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
# Option B: read from .nvmrc (preferred — stays in sync automatically)
# - uses: actions/setup-node@v4
# with:
# node-version-file: '.nvmrc'
# cache: 'npm'
- run: npm ci
- run: npm test
GitLab CI
image: node:20-bullseye # pin — never use node:latest
stages:
- install
- test
install:
stage: install
script:
- npm ci
test:
stage: test
script:
- npm test
Railway (via environment variables)
# Set in Railway dashboard → Environment Variables NIXPACKS_NODE_VERSION=20.19.1 # exact version for full reproducibility # Or use the major-version shorthand: NIXPACKS_NODE_VERSION=20
EEFA: If you’re deploying n8n on Railway from the official template, the Docker image already has the correct Node version baked in. The NIXPACKS_NODE_VERSION variable only matters for npm‑based deployments, not Docker‑based ones.
7c. Apple Silicon (M1 / M2 / M3) Specific Fix
Apple Silicon Macs run arm64 natively but can also run x86 processes via Rosetta 2 emulation. If nvm or Node.js was installed under Rosetta (in an x86 terminal), native modules compiled for arm64 will fail — and vice versa. This is a common silent source of node version errors on Macs upgraded to Apple Silicon.
Check your architecture first:
node -e "console.log(process.arch)" # Should output: arm64 (not x64) # If it shows x64, your Node was installed under Rosetta — reinstall natively
Fix – reinstall nvm and Node natively on arm64:
# Step 1: Open a native Terminal (not via Rosetta) — in macOS Finder: # Right-click Terminal → Get Info → uncheck "Open using Rosetta" # Step 2: Remove Homebrew Node if present brew uninstall node # remove system Node that may conflict # Step 3: Reinstall nvm in native arm64 terminal curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.zshrc # Step 4: Install and use Node 20 (arm64 native) nvm install 20 nvm use 20 node -e "console.log(process.arch)" # → arm64 # Step 5: Clean install n8n npm cache clean --force npm install -g n8n
EEFA: After upgrading macOS (to Sonoma, Sequoia, or later), Xcode Command Line Tools sometimes need reinstalling even if they were previously present. Run xcode‑select ‑‑install before debugging any native module compilation failure on a Mac that just received an OS update.
Docker is the escape hatch: If native compilation keeps failing on Apple Silicon, using the official n8n Docker image sidesteps all architecture issues. The n8n image is published for both amd64 and arm64:
docker run -it --rm \ -p 5678:5678 \ -v ~/.n8n:/home/node/.n8n \ docker.n8n.io/n8nio/n8n
7d. Windows‑Specific Fix (Expanded)
Windows is the most error‑prone environment for npm‑based n8n installations because native module compilation requires the Microsoft C++ Build Tools, which are not installed by default. Version errors on Windows often mask a second underlying problem.
Step 1: Install nvm‑windows and the correct Node
# Download and run the nvm-windows installer from: # https://github.com/coreybutler/nvm-windows/releases # Then in PowerShell (as Administrator): nvm install 20.19.1 nvm use 20.19.1 node -v # → v20.19.1
Step 2: Install Microsoft C++ Build Tools
# Run in PowerShell as Administrator — installs Visual Studio Build Tools + Python npm install -g --production windows-build-tools # Or install manually: # https://visualstudio.microsoft.com/visual-cpp-build-tools/ # Select: "Desktop development with C++" workload
Step 3: Add Windows Defender exclusion to prevent file locking
Windows Defender and antivirus software routinely lock files inside node_modules during npm install, causing EPERM errors that look like Node version errors. Add an exclusion before installing:
# PowerShell as Administrator Add-MpPreference -ExclusionPath "C:\Users\\AppData\Roaming\npm" Add-MpPreference -ExclusionPath "C:\Users\\.n8n"
Step 4: Install n8n
npm install -g n8n n8n start
EEFA: Docker Desktop for Windows eliminates all of the above complexity. If you’re running n8n on Windows in a production or team context, Docker is strongly preferred over a native npm install.
7e. Upgrading to n8n 2.x: Node Version Migration Guide
n8n 2.0 (released December 2025) is a hardening release that dropped support for several legacy configurations, including Node 18. If you’re upgrading from n8n 1.x on Node 18, you must upgrade Node first — upgrading n8n without doing so will result in immediate startup failure.
Correct migration order:
- Back up your n8n data directory (
~/.n8nor the Docker volume). - Check your current n8n and Node versions:
node ‑v && n8n ‑‑version - Switch to Node 20 via nvm:
nvm install 20 && nvm use 20 && nvm alias default 20 - Uninstall the old n8n:
npm uninstall ‑g n8n - Install n8n 2.x:
npm install ‑g n8n - Run the migration tool before activating workflows: check n8n docs for the v2.0 migration report tool.
- Start n8n and verify:
n8n start
EEFA: n8n 2.0 also disabled the ExecuteCommand and LocalFileTrigger nodes by default for security. If your workflows use these, check the v2.0 breaking changes docs before upgrading — this is unrelated to the Node version but commonly discovered at the same time.
8. FAQ
Q: Which Node version should I use with n8n in 2025‑2026?
Node 20 LTS is the safest production choice for n8n 2.x. It satisfies the minimum requirement (20.19), is actively maintained until April 2026, and has the broadest native module compatibility including isolated‑vm. Node 22 LTS is also supported and maintained until April 2027 — choose it if you’re starting a fresh deployment and want longer LTS coverage.
Q: Can I run n8n on Node 24?
Yes — Node 24.x is within n8n’s supported range (>=20.19 <25). However, Node 24 became Current in April 2025 and enters Active LTS in October 2025. Community reports indicate it works but may have occasional isolated‑vm edge cases. For maximum stability, Node 20 or 22 LTS is preferred.
Q: Can I run n8n on Node 18?
Not with n8n 2.x. Node 18 reached End‑of‑Life in April 2025 and n8n 2.x dropped support for it. If you are on n8n 1.x you can still use Node 18, but you should plan an upgrade. Running any EOL Node version in production is a security risk.
Q: Can I run n8n on Node 25?
No. Node 25 is an odd‑numbered (unstable/development) release. Its ABI (141) is not compatible with the pre‑built isolated‑vm binaries n8n ships. Downgrade to Node 24.x (the latest even‑numbered release) and all issues resolve.
Q: I’m on Windows and nvm fails to install. What now?
Use nvm‑windows (a separate project from nvm) — download from github.com/coreybutler/nvm‑windows/releases. Alternatively, download the official Node.js MSI for the LTS version and install it directly. See Section 7d for the full Windows fix sequence.
Q: Does npm ci help with version errors?
Yes, but only after you’ve already switched to a compatible Node version. npm ci performs a clean install based on package‑lock.json, eliminating leftover binaries from a previous Node version. If you run npm ci while still on an unsupported Node, it will also fail with the same engine error.
Q: My PaaS (Railway / Render / Heroku) keeps picking the wrong Node version. How do I pin it permanently?
Each platform has a different mechanism — see the full table in Section 7. The most cross‑platform solution is to add "engines": {"node": "20.x"} to your package.json: most PaaS providers read this field and pin the build accordingly. For Docker‑based deployments on any PaaS, specify the exact image tag rather than :latest.
Q: After switching Node, n8n starts but my Code nodes crash. Why?
This indicates the isolated‑vm native module was compiled for a different ABI than the new Node version. The fix is to force a clean reinstall of n8n after switching: npm uninstall ‑g n8n && npm cache clean ‑‑force && npm install ‑g n8n. If you use the external task runner (Docker), also pull the latest n8nio/runners image.
8a. Troubleshooting Decision Tree
Use this tree to find the right fix in under 3 minutes.
| Symptom | Likely cause | Go to |
|---|---|---|
| Error message says “Node X is not supported” | Wrong Node major version | Section 3 — switch via nvm |
No native build was found for ... abi=141 |
Running Node 25 (odd/unstable) | Section 5 — downgrade to Node 24.x |
| PaaS deployment fails at startup | Platform picked Node 23+ automatically | Section 7 / 7b — pin platform Node version |
| Apple Silicon – build works but n8n crashes | x64 binary installed under Rosetta | Section 7c — reinstall natively |
| Windows – EPERM or file lock during install | Windows Defender locking node_modules | Section 7d — add Defender exclusion |
| Switched Node, still getting ABI error | Old n8n binaries not removed | Section 4.3 — clean reinstall |
| n8n 1.x → 2.x upgrade fails at start | Still on Node 18 (dropped in 2.x) | Section 7e — upgrade Node before n8n |
| Docker container fails on startup after pull | Custom Dockerfile using node:latest |
Section 7a — pin image version |
Conclusion
Running n8n on a supported Node LTS is non‑negotiable for production stability. As of 2025‑2026, the supported range is Node 20.19 through 24.x – Node 18 is no longer supported and Node 25 causes ABI failures in the isolated‑vm module. The core fix is always the same: verify the runtime with node ‑v, switch to a supported LTS via nvm, force a clean reinstall of n8n, and lock the version in a .nvmrc file to prevent future drift.
For Docker, use the official n8n image or pin node:20‑bullseye in a custom Dockerfile. For PaaS platforms, set the Node version via the platform‑specific environment variable before deploying. For Apple Silicon Macs, confirm process.arch === 'arm64' before any install. For CI/CD, use actions/setup‑node with an explicit version or a .nvmrc file. Following these steps eliminates every class of Node version incompatibility documented in n8n’s GitHub issues and community forum.
