os.WriteFile rewrites a file in place, so how can a concurrent os.ReadFile of it return half a document and a nil error?

## The scenario A code generator emits `.go` files with `os.WriteFile`. Something else — a watcher, a build step, another service — reads those files whole with `os.ReadFile`. Occasionally the reader fails with a parse error partway through a file, and rerunning it makes the problem vanish. The file on disk, inspected afterwards, is perfectly fine. ## Why it happens `os.WriteFile` is not a swap. It is: ``` OpenFile(name, O_WRONLY|O_CREATE|O_TRUNC, perm) Write(data) Close() ``` `O_TRUNC` sets the file's length to zero at open time. Then the data goes out, possibly in more than one underlying write for a large slice. During that interval, the file's length is zero, then some prefix, then finally the full new contents. Those intermediate states are not a race in the abstract sense — they are what the file genuinely is at that instant, visible to anything that looks. There is no locking. Unix filesystems do not serialise a reader against a writer for you, and Go's `os` package adds none. The reader is not doing anything wrong; it is reading a file that is currently short. ## Why there is no error This is the part that makes the bug expensive. `os.ReadFile` reads until end of file, and end of file is its success condition — it returns `err == nil`, never `io.EOF`. If it reaches end of file after 300 bytes because that is all there is right now, that is a completely successful read of 300 bytes. So the I/O layer reports nothing. The error appears one level up, in whatever consumes the bytes: a JSON decoder saying unexpected end of input, a Go parser complaining about an unexpected end of file, a template failing to compile, a checksum mismatch. Every one of those points at the parser, not the filesystem, which is why teams lose hours to it. ## The signature of the bug - Intermittent, and correlated in time with the writer running. - Never reproducible under a debugger or a rerun, because by then the write has finished. - The file on disk is valid when you go and look. - The failure rate rises with file size — a larger payload means a longer window between truncation and the final write — and with how often the writer runs. - Two readers can disagree, one succeeding and one failing on the same path at the same second. To reproduce it deliberately, run the reader in a tight loop while the writer rewrites the file repeatedly, and assert on the length of what comes back rather than on the parse. You will see zero-length and prefix-length reads directly. ## Why an os.Stat size check does not fix it The instinct is to stat the file first and only read if the size looks right. That does not work, for two independent reasons. First, it is a check followed by a use, with a gap in between. The size `os.Stat` reports describes the file at the moment of the stat; by the time you open and read, the writer may have truncated it. You have moved the window, not closed it. Second, `os.ReadFile` does its own internal stat purely as an **allocation hint** — it sizes the initial slice from it and then reads to end of file regardless, growing if there is more and returning less if there is less. The size is never a contract on how many bytes you get. Files that report a size of zero, such as many synthetic files, still read correctly for exactly this reason. So even the number that `os.ReadFile` itself sees does not constrain the result. A length check *after* the read is more honest — "I expected at least N bytes" — but it is a heuristic, not a fix, and it cannot distinguish a truncated read from a legitimately shortened file. ## The same hazard inside one process Nothing about this requires two processes. Two goroutines, one calling `os.WriteFile` and one calling `os.ReadFile` on the same path, hit it identically. The Go race detector will not find it: there is no shared memory being accessed unsynchronised, only a shared file, and `-race` instruments memory, not filesystem ordering. Reasoning about the ordering yourself is the only tool. ## The real conclusion `os.WriteFile` is an excellent tool for a file you own exclusively: output nobody reads until you say so, a fixture written before a test starts, a file rewritten while the system is quiescent. It is the wrong tool the moment another reader can arrive at an arbitrary time, because it has no story for making the new contents appear as a unit — it deliberately destroys the old contents first. The second, quieter consequence of the same design: if the write fails midway, the old contents are already gone. So the exposure is not only to concurrent readers but to any crash during the write. Whenever the contents of a path must always be a complete, valid document, replacing the file as a whole rather than rewriting it in place is the property you need, and it is a different technique with its own mechanics. ## What an interviewer is checking That you can trace a parser-level symptom back to an I/O-level cause; that you know a short read is a successful read; that you do not reach for a stat-then-read check and call it solved; and that you can articulate what guarantee `os.WriteFile` never claimed to give.