Why Our WebSocket Takes 23 Seconds to Connect (React StrictMode + IPv6)

Our ACP demo server connects to a backend via WebSocket. The connection should take under 500ms — our Playwright pressure test confirmed this. But when opening the browser, it consistently took 20-30 seconds. The UI showed a blank "connecting..." state for an eternity.

This post documents the debugging strategy that found three stacked root causes, and the fix.

Symptoms

Opening localhost:5688 after a fresh browser launch:

• First WebSocket attempt hangs for exactly 10 seconds, then errors
• Second attempt also hangs for exactly 10 seconds
• Third attempt connects in ~300ms
• Total: ~23 seconds of dead time

Debugging Strategy: Logs on Both Sides

The trap with WebSocket latency is that the problem can live on either side. We started by adding logs to the server — and saw nothing wrong. Connections appeared instantly from the server's perspective. That was the clue: the bottleneck was entirely client-side.

Step 1: Structured Backend Logging

We replaced all hand-rolled console.log calls with pino structured logging. Every WebSocket lifecycle event got a structured log with timing fields:

// Before: string interpolation scattered through business logic
console.log(`[ws] open client=${clientId} path=${path} ${Date.now()}ms`);

// After: structured fields, automatic timestamps, separate from business logic
log.info({ client: clientId, path, boot: bootMs() }, "ws: open");

This gave us clean, filterable server logs with boot (ms since server start), durationMs on every operation, and session IDs for correlation. We could immediately see that the server-side connection handling took <1ms. The problem wasn't here.

Step 2: Client-Side Profiling Timestamps

We added performance.now() timestamps at every WebSocket lifecycle point in the React component, measured relative to page navigation start:

function pageMs(): string {
  return performance.now().toFixed(0) + "ms";
}

// Every lifecycle point gets a timestamp
console.log(`[${pageMs()}] ws new WebSocket(${wsUrl})`);
// ...
console.log(`[${pageMs()}] ws OPEN (handshake=${handshakeMs}ms)`);
// ...
console.log(`[${pageMs()}] ws CLOSED code=${ev.code}`);

The key points instrumented:

• useEffect mount/cleanup — when React runs the effect
• new WebSocket() constructor — when the connection attempt starts
• onopen — when the TCP + WS handshake completes
• onerror / onclose — when connections fail
• onmessage (first) — when the first server message arrives
• Connection timeout — when we give up and retry

Step 3: Read the Timeline

With both sides instrumented, we could read the full story:

[970ms]  useEffect mount → new WebSocket(ws://localhost:5689/ws)
[971ms]  useEffect cleanup → close(readyState=CONNECTING)
[972ms]  useEffect mount → new WebSocket(ws://localhost:5689/ws)
[10981ms] ERROR (10 seconds later!)
[11981ms] retry → new WebSocket
[21983ms] ERROR (another 10 seconds!)
[22984ms] retry → new WebSocket
[23300ms] OPEN (316ms handshake)

Three patterns jumped out:

1. mount → cleanup → mount within 2ms — React StrictMode double-mount
2. Exactly 10s gaps — our connection timeout, not a network issue
3. 316ms handshake on the successful attempt — way too slow for localhost

Each pattern pointed to a distinct root cause.

Root Cause 1: React StrictMode Creates Zombie WebSockets

In development, React StrictMode double-mounts every component: mount → unmount → mount. Our WebSocket useEffect:

1. Mount 1 (970ms): Creates WebSocket #1, starts TCP handshake
2. Cleanup (971ms): Calls ws.close() on WebSocket #1 — now in CLOSING state
3. Mount 2 (972ms): Creates WebSocket #2, starts TCP handshake

WebSocket #1 is now a zombie — its JavaScript handlers are nulled, but the browser is still completing the TCP close handshake with the server. Chrome's connection pool sees an active connection to localhost:5689 and queues WebSocket #2 behind it.

The result: WebSocket #2 can't connect until WebSocket #1's TCP close fully completes, which is gated by our 10-second connection timeout.

Root Cause 2: 10-Second Connection Timeout

We had a "safety" timeout that killed WebSocket connections after 10 seconds:

connectTimeout = setTimeout(() => {
  if (ws.readyState === WebSocket.CONNECTING) {
    ws.close(); // kill it, try again
    reconnectTimer = setTimeout(connect, 1000);
  }
}, 10_000); // 10 seconds!

For a localhost connection that should complete in <100ms, 10 seconds is absurd. Each failed attempt burned the full 10 seconds before retrying.

Root Cause 3: localhost Triggers IPv6 Fallback

The WebSocket URL used localhost:

const wsUrl = `ws://localhost:5689/ws`;

Chrome resolves localhost and tries IPv6 (::1) first. Our Bun server listens on 0.0.0.0 (IPv4 only). Chrome's IPv6 attempt fails, then it falls back to IPv4 127.0.0.1. This added hundreds of milliseconds to every successful connection — the "316ms handshake" for what should be a <10ms localhost connection.

The Fix

1. Remove StrictMode. This is a dev tool, not a production app. No zombie WebSockets, no queued connections.

// Before
createRoot(root).render(<StrictMode><App /></StrictMode>);

// After
createRoot(root).render(<App />);

2. Reduce connection timeout to 1 second with 100ms retry.

connectTimeout = setTimeout(() => {
  if (ws.readyState === WebSocket.CONNECTING) {
    ws.close();
    setTimeout(connect, 100);
  }
}, 1000);

3. Use 127.0.0.1 instead of localhost to skip IPv6 resolution entirely.

const wsHost = location.port === "5688"
  ? "127.0.0.1:5689"
  : location.host;

Result

Before: 23 seconds. After: under 500ms. Matching what our Playwright pressure test always showed.

Validating with a Pressure Test

We wrote a Playwright-based pressure test that measures real cold-start latency — spawning the server and connecting immediately without waiting for warmup, just like a real user:

// Phase 1: Cold start — connect immediately, retry until server is ready
const coldResult = await measureTab(context, "cold-1", "cold",
  `ws://127.0.0.1:${port}/ws`);

// Phase 2: Warm — open N tabs simultaneously
const warmResults = await Promise.all(
  Array.from({ length: 20 }, (_, i) =>
    measureTab(context, `warm-${i+1}`, "warm",
      `ws://127.0.0.1:${port}/ws`)));

Results after the fix: cold start p99 < 200ms, warm p99 < 500ms for 20 simultaneous tabs.

Key Takeaway

The connection was fast. The infrastructure around it — React StrictMode, aggressive timeouts, DNS resolution — made it slow. None of these would show up in a server-side profiling session.

The debugging strategy that worked:

1. Add structured logs to the backend — ruled out server-side causes instantly
2. Add timestamped profiling to the frontend — revealed the exact timeline of what the browser was doing
3. Read the numbers — the patterns (mount/cleanup/mount, exact 10s gaps, 316ms handshake) each pointed directly at a root cause
4. Validate with a pressure test — confirmed the fix works under load, not just for a single tab

When debugging latency: measure from the user's perspective first. The server was fine. The browser was the bottleneck.

// 改造前：字符串拼接散落在业务逻辑中
console.log(`[ws] open client=${clientId} path=${path} ${Date.now()}ms`);

// 改造后：结构化字段，自动时间戳，与业务逻辑分离
log.info({ client: clientId, path, boot: bootMs() }, "ws: open");

function pageMs(): string {
  return performance.now().toFixed(0) + "ms";
}

// 每个生命周期节点都有时间戳
console.log(`[${pageMs()}] ws new WebSocket(${wsUrl})`);
// ...
console.log(`[${pageMs()}] ws OPEN (handshake=${handshakeMs}ms)`);
// ...
console.log(`[${pageMs()}] ws CLOSED code=${ev.code}`);

[970ms]  useEffect 挂载 → new WebSocket(ws://localhost:5689/ws)
[971ms]  useEffect 清理 → close(readyState=CONNECTING)
[972ms]  useEffect 挂载 → new WebSocket(ws://localhost:5689/ws)
[10981ms] ERROR（整整 10 秒后！）
[11981ms] 重试 → new WebSocket
[21983ms] ERROR（又是 10 秒！）
[22984ms] 重试 → new WebSocket
[23300ms] OPEN（316ms 握手）

connectTimeout = setTimeout(() => {
  if (ws.readyState === WebSocket.CONNECTING) {
    ws.close();
    reconnectTimer = setTimeout(connect, 1000);
  }
}, 10_000); // 10 秒！

const wsUrl = `ws://localhost:5689/ws`;

// 修改前
createRoot(root).render(<StrictMode><App /></StrictMode>);

// 修改后
createRoot(root).render(<App />);

connectTimeout = setTimeout(() => {
  if (ws.readyState === WebSocket.CONNECTING) {
    ws.close();
    setTimeout(connect, 100);
  }
}, 1000);

const wsHost = location.port === "5688"
  ? "127.0.0.1:5689"
  : location.host;

// 阶段 1：冷启动 — 立即连接，重试直到服务器就绪
const coldResult = await measureTab(context, "cold-1", "cold",
  `ws://127.0.0.1:${port}/ws`);

// 阶段 2：热连接 — 同时打开 N 个标签页
const warmResults = await Promise.all(
  Array.from({ length: 20 }, (_, i) =>
    measureTab(context, `warm-${i+1}`, "warm",
      `ws://127.0.0.1:${port}/ws`)));