Debugging WebSocket JSON with Formatters

When a WebSocket bug only appears in real time, the hardest part is often reading the payload fast enough to spot the wrong field, missing property, or malformed nested object. A JSON formatter turns dense one-line frames into something you can scan, validate, and compare in seconds.

Start with the browser inspector, then move the suspicious frame into an offline formatter when you need cleaner diffs, stronger validation, or safer handling of production data. That is usually faster and safer than pasting sensitive payloads into random online tools.

Start with the WebSocket Inspector

Current browser devtools already expose a lot of WebSocket detail. Use that first so you can see message order, direction, and timing before you isolate a specific JSON payload.

1. Chrome and Chromium-based browsers

• Open DevTools, go to the Network panel, and filter to WS.
• Select the socket connection and open the Messages tab.
• Use the message list to pair the outbound frame with the inbound response or broadcast that follows it.
• Chrome keeps the last 100 messages in that table, so reproduce the smallest failing sequence you can when the socket is noisy.

This is usually enough to spot bad message ordering, duplicate sends, or a payload that is clearly missing a field before you do any deeper formatting.

2. Firefox

• Open the Network panel, filter to WS, and select the active connection.
• Inspect the live-updating response view as frames arrive.
• Filter sent, received, and control frames so heartbeat traffic does not hide the real issue.
• Firefox can expand several structured protocols, including plain JSON, which helps when your app uses a wrapper such as Socket.IO or SignalR around the business payload.

When a JSON Formatter Helps More

Browser inspectors are good for capture. A formatter becomes more useful when the frame is valid JSON but not easy to reason about.

• Large nested payloads: Indentation makes it easier to scan IDs, flags, and arrays without missing one field in a long line.
• Validation: A formatter immediately tells you whether the copied frame is valid JSON or a truncated log line.
• Diffing: Pretty-printed JSON is much easier to compare against a known-good frame.
• Privacy-sensitive debugging: An offline formatter is the better default for tokens, email addresses, customer IDs, and internal payloads because the data stays on your machine.

Here is the same WebSocket message as raw text and as formatted JSON:

{"type":"presence.update","requestId":"req_42","payload":{"userId":"user123","status":"online","rooms":["ops","sales"],"meta":{"traceId":"8f0ac1","retry":false}}}

{
  "type": "presence.update",
  "requestId": "req_42",
  "payload": {
    "userId": "user123",
    "status": "online",
    "rooms": ["ops", "sales"],
    "meta": {
      "traceId": "8f0ac1",
      "retry": false
    }
  }
}

A Fast Workflow for Real Bugs

1. Reproduce one action at a time so the socket log stays readable.
2. Find the outbound frame that triggered the problem, then the next inbound frame that should answer it.
3. Copy the suspicious JSON into an offline formatter and validate it before changing code.
4. Compare it with a working frame from the same endpoint or event type, paying attention to types as well as values.
5. Check correlation fields like requestId, traceId, message type, timestamps, booleans, and nullable properties.

This workflow catches a large share of real issues: a number serialized as a string, a missing nested key, an unexpected null, or a payload envelope that changed shape during a deploy.

Common WebSocket JSON Problems

The formatter only helps after you know what kind of frame you actually have. These are the cases that usually waste the most time.

• JSON wrapped inside a string: Many backends send an envelope where the outer frame is JSON but the inner payload field is another JSON string. You may need to parse twice.
• Heartbeat and control frames: Ping, pong, and protocol control messages are not business payloads. Filter them out before comparing JSON.
• Binary frames: If the socket sends ArrayBuffer, Blob, protobuf, or compressed data, a JSON formatter is not the right tool until you decode the bytes first.
• Invalid JSON copied from logs: Truncated log lines, extra commas, or broken escaping make a valid message look like a server bug when it is really a logging problem.

A small helper like this is more practical than a bare JSON.parse() during debugging:

function formatWebSocketFrame(frame: string | ArrayBuffer | Blob) {
  if (frame instanceof ArrayBuffer) {
    return `Binary frame (${frame.byteLength} bytes). Decode it before treating it as JSON.`;
  }

  if (frame instanceof Blob) {
    return `Blob frame (${frame.size} bytes). Read it as text before parsing.`;
  }

  try {
    const parsed = JSON.parse(frame);

    if (
      parsed &&
      typeof parsed === "object" &&
      "payload" in parsed &&
      typeof parsed.payload === "string"
    ) {
      try {
        return JSON.stringify(
          { ...parsed, payload: JSON.parse(parsed.payload) },
          null,
          2
        );
      } catch {
        // payload was ordinary text, not nested JSON
      }
    }

    return JSON.stringify(parsed, null, 2);
  } catch (error) {
    return `Not valid JSON: ${(error as Error).message}\n\n${frame}`;
  }
}

The important part is not the indentation itself. It is the branching: strings get parsed, nested JSON gets a second pass when needed, and binary frames get called out immediately instead of silently failing.

What to Check in the Formatted Output

• Message type: Verify the top-level event name before reading the payload details.
• Correlation fields: Check requestId, traceId, room IDs, and user IDs so you know the response belongs to the request you are investigating.
• Type mismatches: Bugs often come from "42" versus 42 or"false" versus false.
• Nullable and optional fields: Confirm whether the server omitted a key entirely or sent it as null.
• Timestamps and ordering: A valid payload can still be wrong if messages arrive in the wrong sequence.

Conclusion

Debugging WebSocket JSON gets much easier once you separate capture from inspection. Use the browser network tools to find the right frame, then run that payload through an offline formatter to validate it, expand it, and compare it with a known-good message. That combination is simple, current, and reliable enough to catch most real production issues without adding new tooling to your app.