openclaw - 💡(How to fix) Fix [Bug] gateway can't recover from npm chunk-hash replacement during in-place upgrade — graceful shutdown depends on now-missing chunk [3 comments, 3 participants]

Bug type

Crash (process/app exits or hangs)

Beta release blocker

No

Summary

When npm install -g openclaw@<newver> runs while the openclaw gateway is alive, the new install replaces hash-suffixed chunk files in dist/ (e.g. legacy-config-issues-CClZWCli.js → legacy-config-issues-BxN-Pz1M.js). The running gateway process retains references to the old chunk hashes and on next config reload fails with ERR_MODULE_NOT_FOUND. Worse, the graceful shutdown path itself depends on a now-missing chunk (server-close-DsVPJDIx.js), so openclaw gateway restart --force cannot complete shutdown — only launchctl kickstart -k (or equivalent SIGKILL + respawn) recovers.

Steps to reproduce

1. Have openclaw gateway running (e.g. as gui/501/ai.openclaw.gateway launchd agent).
2. Run npm install -g openclaw@<any newer version where chunk hashes change> — the on-disk dist/*.js filenames change.
3. Trigger any config reload (openclaw doctor --fix, save to openclaw.json, etc.).
4. Observe Cannot find module .../legacy-config-issues-<oldhash>.js repeating in ~/.openclaw/logs/gateway.err.log.
5. Run openclaw gateway restart --force → emits [gateway] shutdown error: Cannot find module .../server-close-<oldhash>.js. Old process never exits.
6. Recovery requires launchctl kickstart -k gui/<uid>/ai.openclaw.gateway (SIGKILL + respawn).

Expected behavior

Either:

• (a) The running gateway should resolve all chunk imports during startup and not lazy-import after that, so an in-place upgrade leaves the running process serving the old (in-memory) code until full restart; or
• (b) The upgrade flow should be atomic from the gateway's perspective — full process exit before the new files land.

In any case, graceful shutdown should not depend on a chunk that may have been deleted: the shutdown handler itself should be resident in memory or eagerly imported at startup.

Actual behavior

Running gateway is left in a state where it can neither reload config nor shut itself down cleanly. Manual launchctl kickstart -k is the only recovery.

OpenClaw version

2026.5.3-beta.3 (upgraded in place from 2026.5.2)

Operating system

macOS 26.4.1 (arm64)

Install method

npm global

Model

openai-codex/gpt-5.5

Provider / routing chain

openclaw -> openai-codex

Logs, screenshots, and evidence

2026-05-04T11:08:17.896+08:00 [reload] config reload skipped (invalid config): : read failed: Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/opt/homebrew/lib/node_modules/openclaw/dist/legacy-config-issues-CClZWCli.js' imported from /opt/homebrew/lib/node_modules/openclaw/dist/io-BcjzQKwO.js
... (repeats every ~600ms in a flap loop)
2026-05-04T11:17:18.124+08:00 [reload] config change requires gateway restart (plugins.installs.brave)
2026-05-04T11:17:18.335+08:00 [gateway] SIGUSR1 restart ignored (not authorized; commands.restart=false or use gateway tool).
2026-05-04T11:17:18.522+08:00 [gateway] shutdown error: Error [ERR_MODULE_NOT_FOUND]: Cannot find module '/opt/homebrew/lib/node_modules/openclaw/dist/server-close-DsVPJDIx.js' imported from /opt/homebrew/lib/node_modules/openclaw/dist/server.impl-B11albXx.js

The hashes the running process wanted are not in the new dist/:

$ ls /opt/homebrew/lib/node_modules/openclaw/dist/legacy-config-issues*.js
/opt/homebrew/lib/node_modules/openclaw/dist/legacy-config-issues-BxN-Pz1M.js
/opt/homebrew/lib/node_modules/openclaw/dist/legacy-config-issues-GeD6gJjS.js
# CClZWCli (the one the running process imported) is gone — was the previous version's hash

Recovery sequence that worked:

launchctl kickstart -k gui/501/ai.openclaw.gateway
sleep 5
ps aux | grep -E "openclaw.*gateway" | grep -v grep   # PID changed; new process running fine on new dist/

Impact and severity

• Affected: anyone upgrading openclaw via npm install -g while the gateway is running (which is the documented happy path).
• Severity: high — gateway is bricked into a no-shutdown state until manual SIGKILL.
• Frequency: very likely on any version bump that produces new chunk hashes (effectively every release, since rollup/vite hashes are content-based).
• Consequence: every npm-driven upgrade has a chance of leaving the user with a flapping, un-shutdown-able gateway, with confusing error messages that point at chunk filenames not at the upgrade itself.

Additional information

• Last known good behavior: in 2026.5.1 era, npm install -g openclaw@<newver> followed by openclaw gateway restart --force was a normal upgrade flow without this bricked state. (The vite/rollup chunk-hash strategy may have been introduced or made more aggressive recently — not 100% confirmed from outside.)
• Suggested mitigation paths:
  • Eager-import the shutdown path (or inline it) so gateway shutdown never touches the file system after startup.
  • Document launchctl kickstart -k (or platform equivalent) as the recommended in-place upgrade path, not gateway restart --force.
  • Have gateway restart --force detect missing-chunk errors and fall through to SIGKILL of the running PID itself.