Your Server-Sent Events emitter writes a final fault block and closes the response, but clients never see that event - why?

## The bytes arrived; the event did not This is the most common Server-Sent Events bug that survives a code review, because every layer looks healthy. Capture the response body and the fault block is visibly there, spelled correctly, with the right field names. The receiving application simply never sees it. Nothing timed out, nothing was dropped, and no error is reported anywhere - because as far as the grammar is concerned nothing went wrong. The client is still waiting for the block to end. The parser is a small state machine over buffers. `data` lines append to a payload buffer, an `event` line sets a type buffer, and **a blank line is the only transition that dispatches**. There is no timer, no size threshold and no end-of-body rule that flushes a partial block. When the response body ends with a block still accumulating, the client discards those buffers. ## Three grammar-level reasons nothing was dispatched | what the emitter wrote | what the client did | delivered? | |---|---|---| | field lines, then the body ended | kept the buffers, then discarded them | no | | `event: fault` and a blank line, no `data` line | found the payload buffer empty, cleared both buffers | no | | `: fault pending` (colon first) | ignored the line entirely | no | | field lines, then a blank line | assembled and dispatched one event | yes | The second row is worth sitting with. A block that names a type but carries no `data` field is not an empty event - it is no event. If you genuinely want to dispatch something with an empty payload, write a bare `data:` line: the field is then present, its value is the empty string, and the payload buffer holds one line feed, which the dispatch step removes to give an empty-string payload. Presence of the field, not content, is what decides. The third row is the comment rule, and it is the reason a debugging line written as `: about to send fault` produces exactly nothing, which is what it is for. ## Why the end of the body is not a dispatch It would be easy to assume that closing the response means "and dispatch whatever you have". The grammar deliberately does not say that, and the reason is that the client cannot tell a deliberate ending from a truncation. A response can end because the emitter finished, because an intermediary cut it, or because the network failed mid-write - and in the last two cases the accumulated bytes are half an event. Delivering them would hand the application a fault report missing its second half, indistinguishable from a real one. Discarding an unterminated block is the safe reading of an ambiguous ending: an event is delivered only when the emitter has explicitly said it is complete. ## Diagnosing it Work in this order, because each step is cheaper than the next: 1. **Read the raw body, not the application's view.** Every event must be followed by an empty line. If the last block is not, you have the answer already. 2. **Count the blank lines against the events you expect.** N events means N blank lines in the body, one per block. 3. **Check each block for at least one `data` line.** A type-only block explains a missing event with no missing bytes. 4. **Check the field spellings literally.** A capitalised or misspelt name is ignored in silence, and a block whose only `data` line was misspelt has an empty payload buffer - which lands you back on row two of the table. 5. **Only then look outside the grammar.** If every block is terminated, well formed and carries data, the cause is no longer the wire format. ## What to write instead The rule for an emitter is one sentence: **the last thing written for any event is its blank line.** Practically that means: - treat "write an event" as one operation that ends with the terminator, never as "write the fields" plus a separate step someone can forget; - when ending a stream deliberately, terminate the final block before ending the body - anything written after that terminator and before the end is discarded; - never rely on the next event's field lines to "push" the previous one out, because they do not: the previous block stays open until a blank line arrives, and the new lines simply join it, producing one corrupted event instead of two good ones. That last failure is the nastier sibling of this bug. A missing terminator in the middle of a stream does not lose one event - it merges two, so the application receives a payload with another event's data appended to it, and often parses it as a single malformed record long after the emitter has moved on.