fix(gateway/ws): downgrade expected 1013 'gateway starting' close-before-connect log to debug (#76361)

lonexreb · lonexreb · commit 032fe7a48f08 · 2026-05-05T13:11:49.000-05:00
Code 1013 'Try Again Later' is exactly what the WebSocket spec says
servers should send to clients connecting during a not-yet-ready
window, and the gateway's own ws-connection message-handler does this
deliberately during the startup-sidecars-pending window. Surfacing the
matching 'closed before connect' line at WARN added one entry per
Control UI client per gateway restart and inflated WARN noise without
flagging anything actionable.

Add an isExpectedStartupClose helper that recognizes (code === 1013 &amp;&amp;
reason includes 'gateway starting') and routes that case through the
debug logger, alongside the existing swiftpm-testing-helper noise
downgrade. The non-startup WARN path is preserved for unexpected
close-before-connect events.

Tests: new ws-connection.startup.test case asserts the 1013 close
during pending startup logs at debug, never warn.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -70,6 +70,7 @@ Docs: https://docs.openclaw.ai
 
 ### Fixes
 
+- Gateway/ws: downgrade the expected RFC 6455 1013 `closed before connect` log to debug only when the close was server-initiated by the `startup-sidecars-pending` cause. Fixes #76361. Thanks @lonexreb.
 - Gateway/OpenAI-compatible: send the assistant role SSE chunk as soon as streaming chat-completion headers are accepted, so cold agent setup cannot leave `/v1/chat/completions` clients with a bodyless 200 response until their idle timeout fires.
 - Agents/media: avoid direct generated-media completion fallback while the announce-agent run is still pending, so async video and music completions do not duplicate raw media messages. (#77754)
 - TUI/sessions: bound the session picker to recent rows and use exact lookup-style refreshes for the active session, so dusty stores no longer make TUI hydrate weeks-old transcripts before becoming responsive. Thanks @vincentkoc.
diff --git a/src/gateway/server/ws-connection.startup.test.ts b/src/gateway/server/ws-connection.startup.test.ts
@@ -125,4 +125,94 @@ describe("attachGatewayWsConnectionHandler startup readiness", () => {
       expect(socket.close).toHaveBeenCalledWith(1013, "gateway starting");
     });
   });
+
+  // Regression for #76361: a 1013 ("Try Again Later") close during the startup
+  // sidecars-pending window is exactly what the WebSocket spec says servers
+  // should do, so the corresponding `closed before connect` log must surface
+  // at debug level rather than warn — otherwise every Control UI client adds
+  // a WARN entry per gateway restart.
+  it("logs 1013 'gateway starting' close-before-connect at debug, not warn (#76361)", async () => {
+    const listeners = new Map<string, (...args: unknown[]) => void>();
+    const wss = {
+      on: vi.fn((event: string, handler: (...args: unknown[]) => void) => {
+        listeners.set(event, handler);
+      }),
+    } as unknown as WebSocketServer;
+    const socket = Object.assign(new EventEmitter(), {
+      _socket: {
+        remoteAddress: "127.0.0.1",
+        remotePort: 1234,
+        localAddress: "127.0.0.1",
+        localPort: 5678,
+      },
+      send: vi.fn((_data: string, cb?: (err?: Error) => void) => {
+        cb?.();
+      }),
+      close: vi.fn((code?: number, reason?: string) => {
+        socket.emit("close", code ?? 1000, Buffer.from(reason ?? ""));
+      }),
+    });
+    const upgradeReq = {
+      headers: { host: "127.0.0.1:19001" },
+      socket: { localAddress: "127.0.0.1" },
+    };
+    const logWsControl = createLogger();
+
+    attachGatewayWsConnectionHandler({
+      wss,
+      clients: new Set(),
+      preauthConnectionBudget: { release: vi.fn() } as never,
+      port: 19001,
+      canvasHostEnabled: false,
+      resolvedAuth: { mode: "none", allowTailscale: false },
+      isStartupPending: () => true,
+      gatewayMethods: [],
+      events: [],
+      refreshHealthSnapshot: vi.fn(async () => ({}) as never),
+      logGateway: createLogger() as never,
+      logHealth: createLogger() as never,
+      logWsControl: logWsControl as never,
+      extraHandlers: {},
+      broadcast: vi.fn(),
+      buildRequestContext: () => createRequestContext() as never,
+    });
+
+    const onConnection = listeners.get("connection");
+    onConnection?.(socket, upgradeReq);
+    socket.emit(
+      "message",
+      JSON.stringify({
+        type: "req",
+        id: "connect-1",
+        method: "connect",
+        params: {
+          minProtocol: PROTOCOL_VERSION,
+          maxProtocol: PROTOCOL_VERSION,
+          client: {
+            id: GATEWAY_CLIENT_NAMES.CLI,
+            version: "dev",
+            platform: "test",
+            mode: GATEWAY_CLIENT_MODES.CLI,
+          },
+          role: "operator",
+          scopes: ["operator.read"],
+          caps: [],
+        },
+      }),
+    );
+
+    await vi.waitFor(() => {
+      expect(socket.close).toHaveBeenCalledWith(1013, "gateway starting");
+    });
+    await vi.waitFor(() => {
+      const debugCalls = logWsControl.debug.mock.calls.filter(
+        ([msg]) => typeof msg === "string" && msg.includes("closed before connect"),
+      );
+      expect(debugCalls.length).toBeGreaterThan(0);
+    });
+    const warnCalls = logWsControl.warn.mock.calls.filter(
+      ([msg]) => typeof msg === "string" && msg.includes("closed before connect"),
+    );
+    expect(warnCalls).toHaveLength(0);
+  });
 });
diff --git a/src/gateway/server/ws-connection.ts b/src/gateway/server/ws-connection.ts
@@ -349,6 +349,18 @@ export function attachGatewayWsConnectionHandler(params: AttachGatewayWsConnecti
       normalizeLowercaseStringOrEmpty(userAgent).includes("swiftpm-testing-helper") &&
       isLoopbackAddress(remote);
 
+    // RFC 6455 close code 1013 ("Try Again Later") is exactly what the
+    // gateway sends to clients that connect during the startup-sidecars-pending
+    // window. The reconnect attempt is expected and healthy — surface it at
+    // debug rather than warn so legitimate WARN inflation stays meaningful.
+    // Tie the downgrade to the server-owned `startup-sidecars-pending` close
+    // cause so a peer that picks code 1013 + reason "gateway starting" on a
+    // non-startup close cannot suppress an otherwise actionable WARN. See #76361.
+    const isExpectedStartupClose = (code: number | undefined, reason: string | undefined) =>
+      closeCause === "startup-sidecars-pending" &&
+      code === 1013 &&
+      normalizeLowercaseStringOrEmpty(reason).includes("gateway starting");
+
     socket.once("close", (code, reason) => {
       const durationMs = Date.now() - openedAt;
       const logForwardedFor = sanitizeLogValue(forwardedFor);
@@ -375,9 +387,10 @@ export function attachGatewayWsConnectionHandler(params: AttachGatewayWsConnecti
         ...closeMeta,
       };
       if (!client) {
-        const logFn = isNoisySwiftPmHelperClose(requestUserAgent, remoteAddr)
-          ? logWsControl.debug
-          : logWsControl.warn;
+        const downgradeToDebug =
+          isNoisySwiftPmHelperClose(requestUserAgent, remoteAddr) ||
+          isExpectedStartupClose(code, reason?.toString());
+        const logFn = downgradeToDebug ? logWsControl.debug : logWsControl.warn;
         logFn(
           `closed before connect conn=${connId} peer=${endpoint ?? "n/a"} remote=${remoteAddr ?? "?"} fwd=${logForwardedFor || "n/a"} origin=${logOrigin || "n/a"} host=${logHost || "n/a"} ua=${logUserAgent || "n/a"} code=${code ?? "n/a"} reason=${logReason || "n/a"}`,
           closeContext,
