Why must a caller process the n bytes from io.Reader.Read before checking its error?

## The convention and its exception Go's baseline rule is simple: if a function returns a non-nil `error`, its other results are zero values and mean nothing. `io.Reader` deliberately breaks that rule, and it is the most consequential exception in the standard library. ```go type Reader interface { Read(p []byte) (n int, err error) } ``` The documented contract says an implementation may return the bytes it managed to read **and** the error that stopped it, in the same call — and that callers should always process the `n > 0` bytes returned before considering the error. The reason is physical: a stream can hand you the last 300 bytes of a file and discover the end of the file in the same underlying operation. Forcing it to report those separately would mean an extra syscall on every stream, so the interface allows both at once and pushes the responsibility onto the caller. ## The bug this creates The habit built by every other Go API produces exactly the wrong loop: ```go for { n, err := r.Read(buf) if err != nil { return err // wrong: buf[:n] may hold real data } process(buf[:n]) } ``` This truncates. It also truncates *intermittently*, which is what makes it expensive. Whether a given reader returns `(300, io.EOF)` or `(300, nil)` followed by `(0, io.EOF)` is entirely up to the implementation. `bytes.Reader` and `strings.Reader` tend to take the second path, so a unit test built on an in-memory reader passes forever. A file, a decompressing reader, a TLS connection or an HTTP response body may take the first, so the same code drops the final record in production against a real source, and only sometimes. The correct loop handles data first and classifies the error afterwards: ```go for { n, err := r.Read(buf) if n > 0 { process(buf[:n]) } if err != nil { if err == io.EOF { return nil // normal end of stream } return err } } ``` ## io.EOF is not a failure The second half of the rule: `io.EOF` reports that the stream ended normally, so it is a termination signal rather than an error condition, and it must be distinguished from every other error. Code that returns `io.EOF` up its own call chain teaches its callers to treat a successful read of a whole file as a failure. The standard library is careful about this in both directions. `io.Copy` copies until the source reports EOF and then returns a **nil** error — a successful `Copy` never returns `io.EOF`. `io.ReadFull` inverts it: it returns `io.EOF` only if no bytes were read at all, and `io.ErrUnexpectedEOF` if it read some but not all of what you asked for, so a truncated record is distinguishable from an empty one. ## The other permitted oddity A `Read` may also return `(0, nil)` — no data, no error, nothing happened. The contract says callers should treat that as a no-op and try again rather than concluding the stream is finished, and that implementations should not return it habitually. A hand-written loop that treats `n == 0` as end-of-stream will hang or exit early depending on which mistake it makes; a loop that keys termination on `io.EOF` alone is immune. ## What to do instead of writing the loop Almost no application code should be calling `Read` directly. The standard library provides shapes that already encode the contract: - `io.Copy(dst, src)` for streaming everything from one place to another, with no buffer management and no EOF handling of your own. - `io.ReadFull(r, buf)` when you need exactly `len(buf)` bytes and want a distinct error for a short read. - `io.ReadAll(r)` when the input is bounded and you want it in memory — bounded being the operative word, since it will happily allocate whatever the source sends. - `bufio.Scanner` for line- or token-oriented input, where `Scan` returns false at the end and `Err` afterwards reports whether that end was EOF or a real failure. Note its default token size limit, which turns an over-long line into an error rather than a silent truncation. When you *are* implementing a `Reader` — a decorator that counts bytes, decrypts, or rate-limits — the same contract binds you as the author: return the bytes you have, do not swallow an error you have already observed, and return `io.EOF` (not a wrapped variant) at the end of the stream, because callers compare against it. ## How this shows up on call The symptom is data loss without an error: the last line of a file missing from an import, a record count off by one that varies with input size, or a checksum mismatch on large payloads only. Nothing logs, because nothing failed — the code faithfully reported the `io.EOF` it was handed and discarded the bytes that came with it. That combination, silence plus size-dependence, is the signature worth recognising.