SSE Tester

Debugging Server-Sent Events: A Practical Guide

Server-Sent Events (SSE) is the protocol behind most modern streaming APIs, LLM token streams, live dashboards, log tailing, notifications, real-time price feeds. It's also one of the simplest protocols on the web: text over HTTP, line-based, no framing. But "simple" doesn't mean "always works", proxy buffering, missing headers, malformed events, and CORS quirks can leave you staring at an endpoint that streams in curl but not in your browser. This tool gives you a focused SSE client to inspect the wire format and diagnose what's going wrong.

The Protocol in 30 Seconds

The server responds with:

Parsing rules:

• Events are separated by \n\n (blank line).
• Within an event, field: value lines.
• Fields: data, event, id, retry. Anything else is ignored.
• A line starting with : is a comment (often used as a keepalive every 15-30s).
• Multiple data: lines in one event are joined with \n in the final payload.
• Whitespace after : is optional (data: x and data:x are equivalent).

The simplicity means you can debug streams by reading raw bytes, no opaque binary framing like WebSockets.

EventSource: The Browser API

readyState values:

• 0 (CONNECTING), initial or reconnecting.
• 1 (OPEN), actively receiving.
• 2 (CLOSED), closed permanently (terminal error or source.close()).

EventSource limitations:

• GET only, can't POST a body.
• No custom headers, can't send Authorization: Bearer ... directly.
• No abort during request, only after connection establishes.
• text/event-stream only, can't process other content types.

For anything beyond simple GET-with-cookie, use fetch streaming instead.

Fetch Streaming (Modern Alternative)

Benefits: custom headers, POST bodies, abort via AbortController, no implicit reconnect (you control retry logic).

This is the pattern used by the Vercel AI SDK, OpenAI's official JS SDK, and most modern LLM clients.

LLM Streaming Patterns

OpenAI Chat Completions stream

Each data: is JSON except the final [DONE] sentinel. The client accumulates choices[0].delta.content into the full message.

Anthropic Messages stream

Uses named events (event: content_block_delta) instead of generic message. Client dispatches based on event name.

Vercel AI SDK Data Stream Protocol

Custom format on top of SSE-like streaming, prefixed lines like 0:"text" for text deltas, d:{...} for finish metadata. Different from pure SSE but uses the same chunked transfer.

Common Issues and Fixes

"Curl works but browser doesn't show events"

Most common cause: CORS. EventSource enforces same-origin or explicit CORS headers. Server must respond with:

Second most common: proxy buffering. Nginx default config buffers responses until full. For SSE:

Cloudflare requires the response to set X-Accel-Buffering: no or use a Worker with the Streams API.

"Events arrive in chunks, not one at a time"

The server isn't flushing after each event. In Node.js/Express:

If you're using compression middleware, exclude SSE routes, gzip will buffer.

"EventSource keeps reconnecting"

EventSource auto-reconnects on disconnect. If your server closes the stream after each event, it'll loop forever, generating "request storms." Either keep the stream open as long as the client wants events, or signal completion clearly (close with a final event, then res.end()).

To stop reconnect from server side, respond with HTTP 204 (No Content) on reconnect attempts.

"Authorization header not working"

EventSource doesn't support custom headers. Workarounds:

1. Query param: /stream?token=${jwt}, but tokens leak into logs.
2. Cookie auth: new EventSource(url, { withCredentials: true }), server sets HttpOnly cookie.
3. Fetch streaming with custom headers (see code above), preferred for modern apps.

"Connection dies after 30 seconds / 1 minute"

Many proxies/load balancers idle-timeout long-lived connections. Solutions:

1. Keepalive comments from server every 15-30s: res.write(': keepalive\n\n').
2. Configure proxy timeouts: increase proxy_read_timeout in Nginx, AWS ALB idle timeout, Cloudflare keepalive.
3. Reconnect logic, accept that connections die, use id: and lastEventId to resume.

"JSON.parse fails on event data"

Multi-line JSON in a single data: field needs joining:

After parsing, the joined data is {\n "key": "value"\n} which is valid JSON. If you join with spaces or skip the newline join, you get an invalid string.

Server Implementation Cheat Sheet

Node.js / Express

Python / FastAPI

Go / net/http

Cloudflare Workers / Edge runtimes

Use the TransformStream API:

Reconnection and Last-Event-ID

EventSource sends Last-Event-ID header on reconnect (the last id: field received). Use this to resume:

This gives "exactly-once" delivery semantics if the server stores events with monotonic IDs.

SSE vs Alternatives

For browser-server one-way streaming, SSE is the simplest correct answer. WebSocket is overkill unless you need client→server messages too. HTTP/2 push is dead. WebTransport is exciting but not broadly deployable yet.

Testing Tips

• Use this tool first, confirm wire format and timing without writing client code.
• curl for raw bytes: curl -N https://api.example.com/stream -H "Accept: text/event-stream", -N disables buffering.
• Browser DevTools Network tab, open a request, click "EventStream" tab to see parsed events.
• Cloudflare/Vercel function logs, make sure your serverless platform supports streaming responses (older runtimes buffered everything).
• Test long-lived connections, let it sit for 5+ minutes; many bugs only appear after idle timeout.
• Test reconnect, kill the server, restart, confirm the client reconnects with Last-Event-ID.

Privacy

This tool opens a direct browser-to-endpoint connection using EventSource (or fetch streaming, depending on options). Events stream into your tab and are rendered locally with no intermediate logging or proxy. The endpoint URL, which may encode bearer tokens in query params or point to internal-only APIs, and the event payloads, which often contain LLM prompts, user data, or live production records, stay in your browser. Open DevTools Network during use: exactly one connection to your endpoint, zero requests anywhere else.