AgentFixboard
OpenLast checked OpenClaw#setup#transport#error-messages

openclaw update leaves the gateway stopped with restart-unhealthy and ECONNREFUSED

openclaw update --yes --json finishes the fetch and build, then returns status: error with reason: "restart-unhealthy" and recovery.reason: "runtime-verification-failed". The gateway unit stays inactive (dead).

From GitHub

openclaw/openclaw

Issue

Difficulty
Easy
Time
~5 min
Steps
2
Fixed in
—
Last checked

Not fixed upstream yet: the issue is open. Source: issue open. Last checked 2026-10-19.

Symptom

openclaw update --yes --json finishes the fetch and build, then returns status: error with reason: "restart-unhealthy" and recovery.reason: "runtime-verification-failed". The gateway unit stays inactive (dead).

Evidence what you'll see

  • The diagnostics file health/gateway-health.json records Gateway not reachable at ws://127.0.0.1:18789 (ECONNREFUSED).
  • The matching status/gateway-status.json has "port": { "port": 18789, "status": "free", "listeners": [] } and rpc.connectFailure.kind: "unreachable".
  • The result JSON has an empty steps array. systemctl --user status showed a clean exit (status=0/SUCCESS) and stayed stopped until a manual start.

Why it happens

The original report says the health check hit ECONNREFUSED while the port was still free, before the new process had finished starting. A later investigation on 8 Sep 2026 says those labels do not establish a startup-timing race, and that the same JSON can appear when the parent health poller never ran. Pull request 148066 is still open and is described as a launchd-supervision repair, not a proof of the Linux outage's cause.

Affected versions

Native systemd user service, git-checkout dev channel (pnpm build). Before: 2026.8.1 (0be4cd75). After the update that stayed down: 2026.9.1 (fcb8eb4d). Ubuntu Linux kernel 7.0.0-29-generic. Comments also record npm-global cases on Ubuntu ARM64 (2026.9.1 → 2026.9.3) and macOS arm64 LaunchAgent ai.openclaw.gateway (2026.9.2 → 2026.9.3).

Fix steps

0 of 2 done

Your check marks stay in this browser only.

How to check it worked

  • After an update, the user unit is active without a manual start, and the JSON result is not reason: "restart-unhealthy" with Gateway not reachable and ECONNREFUSED.

If it still fails

  • A 19 Sep 2026 follow-up on the same host (2026.9.1 → 2026.9.5) again returned restart-unhealthy with empty steps. After a manual start, HTTP listening took about 30–40 seconds (22 plugins).
  • The linked issue does not name a release that closes this path. A 11 Oct 2026 comment on the same host failed earlier with preflight-no-good-commit (Disk quota exceeded) and then fetch-failed (file exceeds limit of 268435456 bytes); those are separate from the restart check.

Sources and credit

Summarized in our own words from these public reports. Credit goes to their authors.

Provided as is, without warranty. Try changes in a non-production environment and back up first. Security-related steps: verify against the official docs. Terms · Request removal or attribution change

Hit an error we don't cover? Submit it