NVIDIA / NVIDIA/OpenShell

gateway install --force should stop existing instance and wait for port release before spawning new one

Open
#979 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

state:stale
Dominant language
Rust
Stars
8.7k
Forks
1.3k
Avg merge
2d 11h
Merged PRs (30d)
253

Description

Summary

openclaw gateway install --force is not idempotent. When invoked while a gateway instance is already running, it spawns a new process without first stopping the existing one, immediately hitting EADDRINUSE on port 18789. The new instance fails to bind, but the old instance keeps running with inconsistent service registration state.

Repro

On a host with an active gateway instance:

openclaw gateway install --force

Observed

From openclaw log (2026-04-26, 5060Ti):

Gateway failed to start: another gateway instance is already listening on ws://127.0.0.1:18789
listen EADDRINUSE: address already in use 127.0.0.1:18789
pid 437908: node.exe
Gateway service appears registered. Stop it first.
Tip: openclaw gateway stop

After this, openclaw daemon status --json reports runtime.status=stopped (split-brain — see companion issue), but port 18789 still has the old node.exe listening.

bonjour watchdog also goes into a re-advertise loop, presumably due to torn mDNS announcement state.

Expected

--force should:

  1. Detect existing instance (registered service or port listener on 18789)
  2. Run the equivalent of gateway stop
  3. Poll until port 18789 has no listener (with a sane timeout — e.g. 30s)
  4. Only then spawn the new instance

If step 3 times out, surface a clear error rather than spawning a doomed second instance.

Impact

Discovered during downstream ship verification (anro-claw issue #825). The workaround for downstream consumers is "don't run --force during verification flows; assume the gateway is already ready" — but --force not being idempotent surprises anyone treating it as a safe re-run.

Companion issue (filed separately): daemon status --json mis-reports stopped when port 18789 has a listener but service registration is torn — should report conflict with the offending PID.

Environment

  • Windows 11, Node 20 (bundled)
  • Observed on 5060Ti dev box during 2026-04-26 ship of downstream installer

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the openclaw gateway install --force and gateway stop command paths, reproducing the issue on Windows with a gateway already listening on port 18789. Trace how the existing service or listener is detected and how stopping completes. Done means force installation waits for port 18789 to be released, reports a clear timeout error, and avoids spawning a second instance.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js
Domain
backend, cli
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.