Skip to content

[Bug]: [WSL2 Mirrored Mode] Gateway fails to start with "another gateway instance is already listening" error #31980

@Chuosen

Description

@Chuosen

Bug type

Regression (worked before, now fails)

Summary

After switching to WSL2 Mirrored mode, gateway systemd service fails to start with "another gateway instance is already listening" error, but port is actually free.

Steps to reproduce

  1. Configure WSL2 with networkingMode=mirrored in .wslconfig
  2. Configure OpenClaw gateway with systemd service
  3. Run: systemctl --user start openclaw-gateway.service
  4. Check logs: journalctl --user -u openclaw-gateway.service

Expected behavior

Gateway should start successfully and listen on configured port (18789).

Actual behavior

Gateway fails to start with error:
"Gateway failed to start: another gateway instance is already listening on ws://127.0.0.1:18789"

But port is actually free (verified with ss -tlnp).
Canvas binds successfully, but WebSocket detection fails immediately after.

OpenClaw version

2026.2.26

Operating system

WSL2 (Windows Subsystem for Linux) on Windows 11

Install method

npm global

Logs, screenshots, and evidence

### Error Logs
canvas host mounted at http://127.0.0.1:18789/__openclaw__/canvas/
Gateway failed to start: another gateway instance is already listening on ws://127.0.0.1:18789
Port 18789 is already in use.


### Port Verification (actually free)

$ ss -tlnp | grep 18789
(no output - port is free)
Manual Start Works
$ npx openclaw gateway --port 18790 --allow-unconfigured
# ✅ Successfully starts on port 18790
.wslconfig Configuration
[wsl2]
networkingMode=mirrored
localhostForwarding=true
autoProxy=true
firewall=true
dnsProxy=true
hostAddressLoopback=true

---

### Impact and severity
Affected users/systems:

All users running OpenClaw on WSL2 with Mirrored mode
Severity: High (blocks systemd service startup)

Frequency: 100% reproducible on WSL2 Mirrored mode

Consequence:

Gateway systemd service cannot start
Must manually start gateway each time WSL starts
EvoMap and other services depending on gateway are affected

---

### Additional information
Last known good version: NAT mode (before switching to Mirrored)

First known bad version: 2026.2.26 with Mirrored mode

Temporary workaround:
Manual start with different port works:

npx openclaw gateway --port 18790 --allow-unconfigured
Root cause analysis:
Race condition in gateway startup - Canvas HTTP binds successfully, but WebSocket detection logic incorrectly detects "another instance" (likely detecting its own Canvas binding). This is specific to WSL2 Mirrored mode network stack.

Impact and severity

No response

Additional information

No response

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingregressionBehavior that previously worked and now fails

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions