openclaw - 💡(How to fix) Fix update.run can report success after package swap even when gateway restart is ignored [1 comments, 2 participants]

Summary

Control UI / Gateway update.run can report success after replacing the installed OpenClaw package, but fail to restart the running gateway. This leaves the old Node process alive while dist/ files on disk have been replaced by the new package, causing runtime ERR_MODULE_NOT_FOUND / plugin SDK incompatibility errors until the operator manually restarts the service.

This appears to be a core update lifecycle issue: package swap and restart acknowledgment are not atomic, and update.run status does not reflect whether the new gateway process actually came up.

Observed behavior

Environment, sanitized:

• Install kind: global/package install under $HOME/.npm-global/lib/node_modules/openclaw
• Service: user systemd openclaw-gateway.service
• Gateway invoked as node .../openclaw/dist/index.js gateway --port <port>
• Core before: 2026.5.3-1
• Core target/after: 2026.5.4
• External Discord plugin was also updated to 2026.5.4
• Control UI client: openclaw-control-ui

Timeline, sanitized:

17:22:27 [gateway] request handler failed:
  Error: Cannot find module '$OPENCLAW_ROOT/dist/runtime-provider-<hash>.js'
  imported from $OPENCLAW_ROOT/dist/extensions/memory-core/index.js
  code=ERR_MODULE_NOT_FOUND

17:22:48 [ws] webchat connected ... client=openclaw-control-ui

17:23:00 [gateway] update.run completed actor=openclaw-control-ui ... restartReason=update.run status=ok
17:23:00 [ws] res ✓ update.run 174080ms ...
17:23:00 [gateway] signal SIGUSR1 received
17:23:00 [gateway] SIGUSR1 restart ignored (not authorized; commands.restart=false or use gateway tool).

17:25:37 [gateway] request handler failed:
  Error: Cannot find module '$OPENCLAW_ROOT/dist/runtime-provider-<hash>.js'
  imported from $OPENCLAW_ROOT/dist/extensions/memory-core/index.js
  code=ERR_MODULE_NOT_FOUND

17:27:04 [discord] message run failed:
  SyntaxError: The requested module 'openclaw/plugin-sdk/channel-streaming'
  does not provide an export named 'formatChannelProgressDraftLineForEntry'

17:27:35 systemd: Stopping openclaw-gateway.service - OpenClaw Gateway (v2026.5.3-1)...
17:27:35 [gateway] signal SIGTERM received
17:27:35 [gateway] shutdown error:
  Error [ERR_MODULE_NOT_FOUND]: Cannot find module '$OPENCLAW_ROOT/dist/server-close-<hash>.js'
  imported from $OPENCLAW_ROOT/dist/server.impl-<hash>.js
17:27:35 systemd: Started openclaw-gateway.service - OpenClaw Gateway (v2026.5.3-1).
17:27:40 [gateway] http server listening (... plugins ...)

After a manual CLI/service restart, the gateway came up on 2026.5.4 and plugin errors cleared.

Expected behavior

For package-based updates, update.run should not report a completed/successful upgrade unless the restart handoff is guaranteed and/or verified.

At minimum:

1. If package files were replaced, the old process must not continue serving requests from the replaced install tree.
2. If restart cannot be authorized/executed, update.run should return a failure or degraded state such as restart_failed, not ok.
3. Control UI should surface “package updated but restart failed; manual restart required” instead of appearing to complete normally.
4. The updater should avoid leaving an old process importing from a mutated dist/ directory.

Why this is dangerous

The failure mode is worse than a normal failed update:

• The package on disk is partially/fully changed.
• The old process continues running.
• Lazy/dynamic imports start resolving against the new package tree.
• Core extensions and plugins can fail unpredictably.
• Channel handlers may fail, so the user may not receive the assistant's status/error response.

In the observed incident, Discord replies failed until the operator manually ran the CLI update/restart.

Suspected cause

update.run appears to:

1. Run the package update successfully.
2. Write/update restart sentinel state.
3. Schedule/emit a SIGUSR1 restart.
4. Return status=ok based on package update success.

But the runtime then logged:

SIGUSR1 restart ignored (not authorized; commands.restart=false or use gateway tool).

So the restart request was not actually accepted by the running gateway. The result returned to Control UI did not reflect this restart failure, and the old process stayed alive against the new package files.

Suggested fix

1. Make package update + restart a verified state machine

For package-swap updates, separate statuses explicitly:

• package_update_failed
• package_updated_restart_scheduled
• package_updated_restart_failed
• package_updated_restart_verified

Control UI should treat only restart_verified as a complete successful upgrade.

2. Use an explicit restart intent for in-process update restarts

Before or immediately after package replacement, write a short-lived restart intent file / token that the SIGUSR1 handler will accept even if normal external SIGUSR1 is disabled.

The SIGUSR1 handler already has an intent path concept; update.run should use that same mechanism or another equivalent internal authorization path so its own restart cannot be rejected as an external/unauthorized SIGUSR1.

3. Verify the new process after restart

For package updates, after scheduling restart:

• wait for old gateway connection to close, or return a “restart pending” response that Control UI polls;
• poll the gateway /health/RPC status until reachable;
• verify version === targetVersion or version !== beforeVersion;
• if verification times out, show a hard warning with exact manual recovery instructions.

4. Do not continue serving after package swap if restart fails

If the package update completed but restart authorization fails, the safest behavior is probably to stop accepting normal requests and surface a maintenance/error state, because the process is now running against an install tree that may no longer match loaded code.

5. Add regression coverage

Suggested tests:

• update.run package mode with restart disabled or unauthorized SIGUSR1 should not return ok as a completed upgrade.
• update.run should include restart scheduling/verification status in its response.
• If SIGUSR1 is ignored, the update sentinel/control-plane response should show restart failure/manual restart required.
• Control UI should display incomplete update state when package update succeeds but restart verification fails.

Additional note

This can combine badly with external plugin updates. Updating an external plugin to the new release before core has restarted can load plugin code that expects newer openclaw/plugin-sdk exports. The safer update flow is to keep core + bundled/external plugin sync and gateway restart coordinated as one operation, with runtime verification at the end.