$cd ../troubleshooting/
High📦 Installation
Node.js Version Too Old — Syntax Errors & tsx Crashes
// OpenClaw's current releases target Node.js 22.14 or newer (24 LTS is fine). Running on Ubuntu's default node 18/20, an old nvm alias, or the Node bundled with another tool causes immediate failures: SyntaxError on optional import syntax, native addons compiled for the wrong ABI, or tsx blowing up before the gateway starts. Symptoms look like random stack traces rather than a clear 'upgrade Node' message. This unofficial guide shows how to check `node -v` in the same context as your gateway (SSH vs systemd), install 22.14+ with nvm/fnm/NodeSource, and rebuild native modules so openclaw doctor and gateway install succeed on Mac Mini and Linux VPS alike.
diagnose.sh
🔍 Is This Your Issue?
?`node -v` reports v18.x, v20.x below 20.18, or anything under v22.14
?Gateway crashes with SyntaxError or tsx module errors on startup
?Native module errors mention NODE_MODULE_VERSION mismatch
?openclaw works on your laptop but fails on VPS with older distro Node
?`openclaw doctor` warns about unsupported Node runtime
check_node.sh
✅ Fix 1 — Check Node Version Everywhere
Compare shell Node vs daemon Node
# Interactive shell node -v which node npm -v # Same checks as gateway would see systemctl --user show-environment | grep -i path grep -E 'ExecStart|Environment' ~/.config/systemd/user/openclaw-gateway.service
Exit code 1 means Node too old
# Quick floor check (bash)
NODE_MAJOR=$(node -p "process.versions.node.split('.')[0]")
NODE_MINOR=$(node -p "process.versions.node.split('.')[1]")
# Need: major >= 22 and (major > 22 or minor >= 14)
node -e "const [M,m]=process.versions.node.split('.').map(Number); if(M<22||(M===22&&m<14)) process.exit(1)"install_node22.sh
✅ Fix 2 — Install Node 22.14+ (nvm / fnm / NodeSource)
Install Node 22 LTS line via nvm
# nvm (common on Mac / Linux) curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash source ~/.nvm/nvm.sh nvm install 22 nvm alias default 22 nvm use 22 node -v
Pick one install method — fnm or NodeSource for servers
# fnm alternative (fast, works well on VPS) curl -fsSL https://fnm.vercel.app/install | bash fnm install 22 fnm default 22 node -v # Ubuntu NodeSource (system-wide, no nvm) # curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - # sudo apt-get install -y nodejs
rebuild_openclaw.sh
✅ Fix 3 — Rebuild Native Modules & Reinstall OpenClaw
Native addons must match new Node version
# Rebuild global openclaw for new Node ABI npm rebuild -g openclaw # Or clean reinstall npm uninstall -g openclaw npm i -g openclaw@latest openclaw --version openclaw doctor
Point service at Node 22 binary, not /usr/bin/node
# Update systemd to use correct node path NODE_PATH=$(which node) # Edit openclaw-gateway.service ExecStart to use $NODE_PATH systemctl --user daemon-reload systemctl --user restart openclaw-gateway openclaw gateway status
💡 Pro Tip: Match Gateway's Node to Your Shell
Interactive SSH often loads nvm; systemd does not. Put nvm/fnm init in the service unit's Environment or use an absolute path to Node 22 in ExecStart. After upgrade, `which node` inside the service context must match `node -v` in your terminal.
🛡️ Prevention Checklist
- • Pin Node 22.14+ in .nvmrc or .node-version at the project root and on gateway hosts
- • Run `node -v` in CI, Docker base image, and systemd — not only on your laptop
- • After OS upgrades (apt upgrade nodejs), re-check version — distro packages lag upstream
- • Avoid mixing Homebrew node, nvm node, and /usr/bin/node on the same host
- • Document required Node version next to openclaw install steps in your runbook
❓ FAQ
Q1. What is the minimum Node version for OpenClaw?
Community testing and recent release notes point to Node 22.14+ as the practical floor. Node 24 LTS works. Node 18 and early Node 20 often fail on modern ESM/tsx paths OpenClaw uses internally. Run `openclaw doctor` — recent versions print an explicit Node version warning when below threshold. When in doubt, install the latest Node 22 patch release rather than the oldest possible minimum.
Q2. Why does node -v show 22 in SSH but gateway still crashes?
systemd, launchd, and cron use a minimal environment without nvm/fnm profile snippets. The gateway service may invoke /usr/bin/node (v18) while your shell uses ~/.nvm/versions/node/v22.x/bin/node. Inspect the service file ExecStart= line. Fix by embedding the full path to Node 22 or sourcing nvm in ExecStartPre. Same issue affects Docker if the base image node:18 while you develop on node:22 locally.
Q3. What errors specifically indicate Node version problems?
Common patterns: `SyntaxError: Unexpected token 'with'`, `Cannot find module` for built-in paths, `ERR_DLOPEN_FAILED` on native modules, tsx/esbuild version mismatch, or `ReferenceError: structuredClone is not defined` on very old runtimes. Stack traces mentioning dist/gateway.js at line 1 often mean the runtime cannot parse the bundle — upgrade Node before debugging application logic.
Q4. Should I use nvm, fnm, or system packages?
nvm and fnm are popular for homelab and Mac Mini — easy multiple versions. For headless Ubuntu VPS, NodeSource setup_22.x script or fnm with a global default works well. Avoid distro nodejs 18 from apt unless you use nvm on top. fnm is faster and works in systemd with absolute paths. Pick one manager; do not stack three Node installs like the dual openclaw binary problem.
Q5. Do I need to reinstall openclaw after upgrading Node?
Recommended. Global npm packages may link native addons compiled for the old Node ABI. Run `npm rebuild -g openclaw` or `npm uninstall -g openclaw && npm i -g openclaw@latest` under the new Node. Then `openclaw doctor` and restart gateway. Skipping rebuild causes obscure MODULE_VERSION mismatch errors even when node -v looks correct.
Q6. Does Raspberry Pi arm64 need a special Node build?
Use official arm64 binaries from Node.js downloads or nvm — do not assume x64 nvm on Pi. Build times for native modules are slower; allow extra minutes on first install. Node 22 arm64 builds exist for Pi 4/5 with 64-bit OS. If native rebuild fails, ensure build-essential python3 are installed. Official repo: github.com/openclaw/openclaw.