solution install high macos linux windows

npm global install: OpenClaw breaks after upgrade/downgrade (missing dist chunk)

Fix OpenClaw global installs that break after a version swap (upgrade/downgrade) with errors like 'Cannot find module ... dist/...chunk...' by doing a clean reinstall and refreshing the gateway service install.

By CoClaw Team •

Symptoms

  • After an npm install -g openclaw@... upgrade or downgrade, OpenClaw becomes unusable.
  • Tool-heavy workflows break (TUI/agent/channel runs), often looking like “tools silently don’t work”.
  • You see a runtime import error such as:
    • Cannot find module '.../openclaw/dist/...chunk....js'
    • Cannot find module '.../tool-loop-detection-....js'

Cause

This is usually not a config problem. It’s a corrupted global package tree after a version swap:

  • A previous build’s content-hashed dist chunk is still referenced somewhere, but the file is no longer present.
  • A simple in-place overwrite (npm install -g openclaw@other-version) can leave you in a half-upgraded state.

Fix

Do a full uninstall, then install the exact version you want.

Install latest cleanly:

npm uninstall -g openclaw
npm install -g openclaw@latest --force

Or pin a known-good version cleanly:

npm uninstall -g openclaw
npm install -g openclaw@2026.3.2

Why this helps: uninstall + reinstall forces npm to rebuild the global package tree from scratch instead of trying to reconcile two versions’ dist chunks.

2) Refresh the gateway service install (if you run as a service)

If you installed the gateway as a background service (launchd/systemd/Scheduled Task), refresh the service definition so it points at the current runtime:

openclaw gateway install --force
openclaw gateway restart

Why this helps: even after a clean npm reinstall, your service can still be running an older path/runtime until it is reinstalled.

3) Verify you didn’t accidentally keep multiple installs

If things still look inconsistent, confirm you’re running the binary you think you are:

which openclaw
openclaw --version

Verify

  • openclaw doctor runs without crashing.
  • Tool calls work again (for example: a small exec, read, or config probe).
  • openclaw gateway status shows the expected service state.

Verification & references

  • Reviewed by:CoClaw Code Team
  • Last reviewed:March 14, 2026
  • Verified on: macOS · Linux · Windows

References

Official docs

  1. OpenClaw docs: /install/updating

Issue threads

  1. OpenClaw GitHub issue #28146
  2. OpenClaw GitHub issue #28206
Want to explore more? Browse all solutions or ask in the Community Forum .
Report a problem

Related Resources

npm install -g fails with EACCES / permission denied
Fix
Fix global install permission errors on Linux/macOS by switching npm's global prefix to a user-writable directory (avoid sudo).
Install: 'inappropriate ioctl for device' when running install.sh
Fix
If `curl ... | sudo bash` prints repeated 'inappropriate ioctl for device' and the OpenClaw installer fails or behaves oddly, rerun the installer with a real TTY (or disable gum), or install via npm directly.
Control UI: dashboard root returns plain-text 'Not Found' after upgrade (pnpm global install)
Fix
Fix cases where the gateway starts normally after an upgrade, but `/` returns plain-text `Not Found` until Control UI assets are copied out of the pnpm global package tree and `gateway.controlUi.root` points at that local copy.
Windows: 'openclaw' is not recognized after install
Fix
Fix Windows PATH issues after installing OpenClaw globally (npm prefix not on PATH, terminal not restarted, or multiple Node installs).
OpenClaw Installation Troubleshooting: Node/NPM, PATH, Windows (WSL2), and Docker
Guide
A layered checklist for the most common 'can't install' / 'command not found' / 'service won't start' failures. Covers Node version, global install permissions, PATH issues, WSL2 systemd, and Docker setup gotchas.
ClawHub Usage Guide: Discover, Evaluate, Install, Upgrade, and Roll Back Skills Safely
Guide
A practical guide to using ClawHub as a skill discovery and distribution channel: how to evaluate maintainers, install in a low-risk way, upgrade without surprises, and keep a real rollback path when a skill fails or disappears.