Why must a Go csv.Writer be flushed with Flush and then checked with Error?

## The buffering chain `csv.NewWriter(w io.Writer)` returns a `*csv.Writer` that holds a `*bufio.Writer` wrapped around your destination. Every `Write(record []string)` call quotes the fields as needed, joins them with `Comma`, appends the line terminator, and puts the bytes in that buffer. Bytes leave the buffer only when it fills up or when you flush. That single design choice explains everything else about the API. ## Why Write's error is not the write's error ```go func (w *Writer) Write(record []string) error ``` This returns an error, and people reasonably assume it means "this record failed". It does not. Almost always the record was simply copied into the buffer and nothing touched the file. When it *does* return non-nil, it is reporting a failure that happened during an earlier automatic flush — the buffered writer holds its first error and keeps returning it. So a loop that dutifully checks every `Write` error still cannot conclude the export succeeded, because the final buffer's worth of records has not been written yet when the loop ends. (There is one immediate failure: an invalid `Comma` — a newline, a carriage return, or an invalid rune — makes `Write` return an error before writing anything.) ## Why Flush cannot report it either ```go func (w *Writer) Flush() ``` No return value. This is deliberate — it makes `defer w.Flush()` legal and tidy — but it means the moment when the bytes actually meet the disk is the moment you have no error to inspect. Whatever went wrong is recorded inside the writer. ```go func (w *Writer) Error() error ``` `Error` reports any error that occurred during a previous `Write` or `Flush`. It is the only way to learn the truth, and it must be called *after* the final `Flush`. ## The correct shutdown sequence ```go w := csv.NewWriter(f) for _, rec := range records { if err := w.Write(rec); err != nil { return err } } w.Flush() if err := w.Error(); err != nil { return err } return f.Close() ``` Three checks, in order: the loop catches an early sticky failure and stops wasting work; `Flush` + `Error` catches the failure of the final buffer; closing the file catches whatever the operating system deferred until then. Reporting success without all three is reporting a guess. ## What the bug looks like in production An export job runs, logs "wrote 48,213 rows", exits 0. The partner reports that the file ends halfway through a row, or is missing the last few hundred records. Nothing in your logs is red, because the only code path that could have gone red — the final flush — either never ran or ran without being asked whether it worked. Disk-full is the same story with the error thrown away instead of the bytes. The near-miss version is worse: `defer w.Flush()` *does* run, the bytes *do* get out most of the time, and the one time the disk is full you still report success. ## WriteAll ```go func (w *Writer) WriteAll(records [][]string) error ``` `WriteAll` writes every record, calls `Flush` itself, and returns the error — so a checked `WriteAll` needs no separate `Error` call and is the right choice when you already hold all the records. What it costs you is that you must hold them: a `[][]string` of the entire output in memory, which is exactly the footprint you were avoiding by streaming rows out of a query or an import. ## The mental model to keep "Buffered writer" is a general idea, but the Go specifics are what get asked: `Write`'s error is sticky and retrospective, `Flush` returns nothing at all, `Error` is the reporter, and `WriteAll` folds the flush in. Once those four facts are in place, the shutdown sequence writes itself, and so does the code review comment on the next `defer w.Flush()` you see standing alone.