fix(gateway): prevent 1006 errors from race condition in WebSocket upgrade by dalefrieswthat · Pull Request #43392 · openclaw/openclaw

dalefrieswthat · 2026-03-11T17:55:09Z

Summary

Fix race condition where WebSocket connections could fail with 1006 (abnormal closure) because the upgrade handler was attached after the HTTP server started listening.

Root cause: The gateway started listening for HTTP connections before the WebSocket upgrade handler was attached. During this window, any incoming WebSocket connection would be dropped (socket destroyed) without a proper close frame, causing client-side 1006 errors.

Changes:

Create WebSocketServer and attach upgrade handlers before the HTTP servers start listening
Add error logging to the upgrade handler's catch block (was previously silent)
Improve 1006 error message with troubleshooting hints (TLS mismatch, gateway not ready, etc.)

Change Type

Bug fix

Scope

Gateway / orchestration

Linked Issue/PR

Closes [Bug]: Gateway shows running, health check says disconnected (1006) #43381

User-visible / Behavior Changes

Before: gateway health could intermittently fail with WebSocket 1006, especially immediately after gateway startup.

After: WebSocket connections are properly handled from the moment the gateway starts listening. The 1006 error message now includes troubleshooting hints when it does occur.

Security Impact

New permissions/capabilities? No
Secrets/tokens handling changed? No
New/changed network calls? No
Command/tool execution surface changed? No
Data access scope changed? No

Repro + Verification

Environment: macOS, Node 22+
Steps:
1. Start gateway: pnpm openclaw gateway run --port 18889 --bind loopback --auth token --token test --allow-unconfigured
2. Immediately run: pnpm openclaw gateway health --url ws://127.0.0.1:18889 --token test
Expected: Health check succeeds
Actual before fix: Health check could fail with 1006 (abnormal closure) if connection arrived during the race window

Compatibility / Migration

Backward compatible? Yes | Config/env changes? No | Migration needed? No

greptile-apps · 2026-03-11T17:56:56Z

Greptile Summary

This PR correctly fixes a startup race condition in the WebSocket upgrade path by restructuring the initialization order in createGatewayRuntimeState. The WebSocketServer is now created and attachGatewayUpgradeHandler is called per HTTP server before listenGatewayHttpServer, ensuring no upgrade requests can arrive on an unhandled socket. It also adds error logging to the previously-silent catch block and improves the 1006 error message with actionable troubleshooting hints.

Changes:

server-runtime-state.ts: WebSocketServer creation and attachGatewayUpgradeHandler moved before listenGatewayHttpServer calls, eliminating the race window
server-http.ts: log parameter added to attachGatewayUpgradeHandler; catch block now logs remote address and error message before destroying the socket
call.ts: formatGatewayCloseError expanded with multi-line troubleshooting hints for 1006 closures
lifecycle.test.ts: Cosmetic reformatting of a vi.fn<>() call, no logic changes

Confidence Score: 5/5

This PR is safe to merge — the fix is minimal, targeted, and correctly eliminates the documented race condition without introducing new risks.
The change simply reorders two existing operations (WSS creation + upgrade handler attachment before listen) with no new logic paths. Error logging in the catch block is additive only. The 1006 message improvement is user-facing text with no behavioral impact. All affected code paths were already exercised in production; the fix narrows a timing window rather than introducing new code branches.
No files require special attention.

_{Last reviewed commit: 68e4af2}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c83771e6a3

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Attach upgrade handlers before HTTP server starts listening. Fixes openclaw#43381

grp06 · 2026-04-20T23:29:37Z

Merged via squash.

Prepared head SHA: 0bca6d3512ee9dd7c6530586ab48a34e65349fee
Merge commit: 7b5527a74e96208cd1d508f2444c9d55ef830c9e

Thanks @dalefrieswthat!

@grp06