Formatting Multi-Line data Fields in SSE #Permalink to this section

Part of Understanding the Event Stream Format.

The text/event-stream wire format is newline-delimited: a blank line terminates each event, and a literal \n inside a field value would be mis-parsed as the end of that field — or the end of the event itself. This is the root cause of the most common SSE payload bug: embedding a JSON object that contains newlines (formatted output, template strings, or newline-escaped text) and finding that the client receives a truncated or empty event.data string.

This guide covers exactly how the SSE protocol specification handles multi-line data, how your server must serialize it, and how the browser’s EventSource object reassembles the lines — with copy-paste server code for Node.js, Python, and Go, plus a validation workflow.

Symptom & Developer Intent #Permalink to this section

You are sending an SSE event whose payload is a multi-line string — typically a pretty-printed JSON object, a stack trace, a template-rendered HTML fragment, or a chunk from an LLM that contains a newline character. The client receives one of these outcomes:

• event.data is empty ("") — the blank line you embedded ended the event before any data line was flushed.
• event.data contains only the text up to the first \n — the subsequent data: fields were silently dropped.
• JSON.parse(event.data) throws SyntaxError: Unexpected end of JSON input — the JSON was split mid-object.
• The stream silently hangs after the malformed event, because the parser is now mis-aligned.

The developer intent is to deliver an arbitrary multi-line string or a structured JSON payload — intact, with newlines preserved — to the EventSource listener.

Root Cause Analysis #Permalink to this section

How the parser sees newlines #Permalink to this section

The WHATWG spec defines the text/event-stream stream as a sequence of UTF-8 lines separated by U+000A LINE FEED (\n), U+000D CARRIAGE RETURN (\r), or \r\n. Every one of those sequences is a field separator, regardless of context. There is no escaping mechanism for literal newlines inside a field value.

The dispatch algorithm works as follows:

1. Read lines until a blank line (\n\n, \r\r, or \r\n\r\n).
2. For each non-blank line, split on the first : to get a field name and value.
3. If the field name is data, append the value, then append \n to the event’s data buffer.
4. On blank line: trim the trailing \n from the buffer, fire the message event.

That append-then-newline rule in step 3 is the mechanism that allows multi-line data. Multiple data: lines are concatenated with \n between them — which is exactly the newline character the original payload contained. The spec is therefore the solution: one literal newline in the payload → one extra data: line in the wire frame.

What goes wrong when you skip this #Permalink to this section

If your server does res.write("data: " + JSON.stringify(obj) + "\n\n") and obj is:

{
  "message": "hello\nworld"
}

The wire frame contains:

data: {
data:   "message": "hello
data: world"
data: }

Wait — that is actually almost correct syntax if every line starts with data: . The problem occurs when you pass a raw multi-line string without prefixing each line. The typical mistake:

// WRONG — embeds a bare newline inside a single data: field
res.write(`data: ${JSON.stringify(obj, null, 2)}\n\n`);

Produces on the wire (JS template literal preserves the newlines):

data: {
  "message": "hello\nworld"
}

The second line "message": ... has no data: prefix. The parser sees it as an unknown field name (everything before the first :) and ignores it. The third and fourth lines are similar. The blank line terminates the event with only the first fragment in the buffer.

Step-by-Step Resolution #Permalink to this section

Step 1 — Split the payload on newlines and prefix each line #Permalink to this section

The canonical fix is a one-liner helper that converts every \n into \ndata: . Apply it to any string you want to send as a data field value.

Node.js / JavaScript

// utils/sse.js
/**
 * Serialize a value as one or more `data:` lines.
 * Handles embedded newlines per WHATWG SSE spec §9.2.6.
 * @param {string} value - raw string payload (may contain \n)
 * @returns {string} wire-format data lines, NOT including the trailing blank line
 */
function dataLines(value) {
  // Replace every \n with \ndata: so each logical line gets its own field
  return "data: " + value.replace(/\n/g, "\ndata: ");
}

// Sending a structured JSON object (compact — no embedded newlines):
function sendEvent(res, payload, eventType = null, id = null) {
  let frame = "";
  if (id != null)        frame += `id: ${id}\n`;
  if (eventType != null) frame += `event: ${eventType}\n`;
  frame += dataLines(JSON.stringify(payload)); // compact JSON: no \n inside
  frame += "\n\n"; // blank line terminates the event
  res.write(frame);
}

// Sending a string that may contain real newlines (e.g. LLM chunk, stack trace):
function sendRawText(res, text) {
  res.write(dataLines(text) + "\n\n");
}

Step 2 — Never pretty-print JSON in the payload #Permalink to this section

Compact JSON (JSON.stringify(obj) with no replacer/space arguments) produces a single-line string with no literal newlines. Embedded string values that happen to contain \n are JSON-escaped to \\n, not actual newlines, so they pass through dataLines() safely.

// GOOD — compact, single line, no embedded \n
const frame = dataLines(JSON.stringify({ msg: "hello\nworld" })) + "\n\n";
// Wire: data: {"msg":"hello\\nworld"}\n\n
// client: JSON.parse(event.data).msg === "hello\nworld"  ✓

// BAD — pretty-printed, literal newlines break the frame
const frame = dataLines(JSON.stringify({ msg: "hello\nworld" }, null, 2)) + "\n\n";
// Wire: data: {\ndata:   "msg": "hello\\nworld"\ndata: }\n\n
// Client reconstructed string: '{\n  "msg": "hello\\nworld"\n}'
// JSON.parse still works here, BUT only because dataLines() handled the \n.
// Skip dataLines() and the frame is corrupt.

Pretty-printed JSON is parseable when dataLines() is applied correctly, but it wastes bytes (see Maximum Payload Size Limits for SSE Streams). Keep payloads compact.

Step 3 — Implement the same helper in Python (FastAPI / Starlette) #Permalink to this section

# sse_utils.py
import json
from typing import Any, Optional

def data_lines(value: str) -> str:
    """Convert a (possibly multi-line) string into prefixed data: lines."""
    return "data: " + value.replace("\n", "\ndata: ")

def sse_frame(
    payload: Any,
    event: Optional[str] = None,
    event_id: Optional[str] = None,
) -> str:
    """
    Build a complete SSE event frame.
    payload is serialized with compact JSON (no indent).
    """
    parts: list[str] = []
    if event_id is not None:
        parts.append(f"id: {event_id}")
    if event is not None:
        parts.append(f"event: {event}")
    parts.append(data_lines(json.dumps(payload, separators=(",", ":"))))
    return "\n".join(parts) + "\n\n"

# FastAPI streaming endpoint
from fastapi import FastAPI
from fastapi.responses import StreamingResponse

app = FastAPI()

async def event_generator():
    for i in range(5):
        payload = {"seq": i, "note": "line one\nline two"}
        yield sse_frame(payload, event="update", event_id=str(i))

@app.get("/stream")
async def stream():
    return StreamingResponse(
        event_generator(),
        media_type="text/event-stream",
        headers={
            "Cache-Control": "no-cache",
            "X-Accel-Buffering": "no",   # defeat nginx proxy buffering
        },
    )

The separators=(",", ":") argument removes all whitespace from the JSON output, preventing any embedded newlines from pretty-printing.

Step 4 — Implement in Go using fmt.Fprintf per line #Permalink to this section

// ssewriter/ssewriter.go
package ssewriter

import (
    "fmt"
    "net/http"
    "strings"
)

// WriteEvent sends a complete SSE event to w, splitting payload on \n.
// eventType and id may be empty strings to omit those fields.
func WriteEvent(w http.ResponseWriter, payload, eventType, id string) error {
    if id != "" {
        if _, err := fmt.Fprintf(w, "id: %s\n", id); err != nil {
            return err
        }
    }
    if eventType != "" {
        if _, err := fmt.Fprintf(w, "event: %s\n", eventType); err != nil {
            return err
        }
    }
    // Split on \n and emit one data: line per segment
    lines := strings.Split(payload, "\n")
    for _, line := range lines {
        if _, err := fmt.Fprintf(w, "data: %s\n", line); err != nil {
            return err
        }
    }
    // Blank line terminates the event
    if _, err := fmt.Fprint(w, "\n"); err != nil {
        return err
    }
    // Flush to the client immediately
    if f, ok := w.(http.Flusher); ok {
        f.Flush()
    }
    return nil
}

strings.Split("hello\nworld", "\n") produces ["hello", "world"], so fmt.Fprintf emits:

data: hello
data: world

The EventSource parser joins them with \n, restoring the original string.

Step 5 — Reassemble on the client #Permalink to this section

No special client code is needed for the plain-string case — event.data already contains the correctly joined string.

// browser client — works for both single-line and multi-line payloads
const es = new EventSource("/stream");

es.addEventListener("update", (e) => {
  // e.data is the fully reassembled string, \n intact
  const obj = JSON.parse(e.data);   // safe for compact JSON
  console.log(obj.note);            // "line one\nline two"
});

es.onerror = (err) => {
  // Log but let EventSource auto-reconnect per retry: interval
  console.error("SSE error", err);
};

For error handling and reconnection UX, wrap the parse call in a try/catch and emit a fallback state when JSON.parse throws — this catches any residual formatting bugs during rollout.

Validation & Monitoring #Permalink to this section

curl inspection #Permalink to this section

# Pipe raw bytes through cat -A to see \n vs \r\n
curl -sN -H "Accept: text/event-stream" https://your-api/stream | cat -A | head -40

A correctly formatted multi-line event looks like:

id: 42$
event: update$
data: {"seq":0,"note":"line one$
data: line two"}$
$

Each line ends with $ (cat -A’s \n marker). A blank line ($ alone) ends the event. If you see a line that does not start with data: , id: , event: , retry: , or : (comment), that line is being silently discarded by every spec-compliant parser.

Browser DevTools #Permalink to this section

Open Network → EventStream (Chrome/Edge) or Network → Response (Firefox). Select your SSE request. The “EventStream” tab shows each parsed event; expand the data field to see the fully reassembled value. If the multi-line payload is intact, you will see the newlines rendered as line breaks in the preview.

Unit test stub (Node.js) #Permalink to this section

// test/sse-multiline.test.mjs
import assert from "node:assert/strict";
import { dataLines } from "../utils/sse.js";

// Spec §9.2.6: parser appends \n after each data: value, then strips trailing \n
function simulateParse(frame) {
  const buffer = [];
  for (const line of frame.split("\n")) {
    if (line.startsWith("data: ")) buffer.push(line.slice(6));
    else if (line === "") break; // blank line = end of event
  }
  return buffer.join("\n"); // spec: join with \n, then strip trailing (already done)
}

const original = "hello\nworld\nthird line";
const frame = dataLines(original);
const reassembled = simulateParse(frame);

assert.equal(reassembled, original, "multi-line round-trip must be lossless");
console.log("PASS");

Run with node --test test/sse-multiline.test.mjs or any Node 18+ test runner.

Wire Format Reference #Permalink to this section

The event ID and retry mechanism fields (id:, retry:) must appear as their own lines and are never part of the data buffer. Mixing them inside a data: value (by embedding a literal id: prefix through a newline) would register as a legitimate id: field — another reason to keep payload serialization strict.

Verification Checklist #Permalink to this section

• dataLines() / data_lines() helper exists in a shared module and is the only place data: prefix is written.
• All JSON payloads are serialized with zero indent (no space / indent argument).
• Unit test confirms round-trip fidelity: simulateParse(dataLines(original)) === original for strings containing \n, \r\n, and escaped \\n.
• curl -sN … | cat -A output shows every non-blank line starting with data: , id: , event: , retry: , or :.
• Browser DevTools EventStream tab shows the full reassembled data value, including embedded newlines.
• X-Accel-Buffering: no header is present in staging and production SSE responses.
• JSON.parse(event.data) in the client is wrapped in try/catch with a meaningful error path.
• Load test with a payload containing 20+ newlines confirms no data loss at p99.

Frequently Asked Questions #Permalink to this section

Related #Permalink to this section

• Understanding the Event Stream Format
• How to Parse the text/event-stream MIME Type Correctly
• Maximum Payload Size Limits for SSE Streams
• Event ID & Retry Mechanism Design
• Buffer Management & Chunked Transfer Encoding