A user reports that your tool corrupted their file. You look at the code, and it is correct. The parse is right, the serialization is right, the tests pass. And the user's file is still broken.
This is the most common bug class in tools that write files, and it is almost never in the logic. It is in the four lines that decide how the file gets written, and those four lines are usually the least reviewed part of the codebase — because they look trivial.
I have written this wrong, shipped it, and had it cost real users real data. Here is what I learned about the failure modes that do not show up in tests.
The bug that passes every test
Writing a file looks like this in almost every language:
writeTo(targetFile, newContent);
The tests call it, the assertions pass, the file contains exactly the expected bytes. Green across the board.
What the test does not cover is what happens when this line is interrupted halfway — the process is killed, the laptop sleeps, the disk fills, the IDE is closed mid-save. In that case the file contains some of the new content and none of the old. There is no valid version of the data left. Not the new one, not the previous one.
For a config file or a document, that is a total loss. And it is not a logic bug — the logic was perfect. The problem is that the operation was never atomic.
Why in-place writes fail on Windows specifically
On POSIX systems, rename() over an existing file is atomic. You can write a temp file and move it into place, and any reader sees either the old file or the new one, never a hybrid.
Windows is different in a way that catches people out. A file opened by another process — including your own tool if you kept a handle open for the editor — cannot be replaced. Files.move(..., ATOMIC_MOVE) throws. So a developer writes a fallback:
try {
Files.move(tmp, target, ATOMIC_MOVE);
} catch (IOException e) {
// fallback: just write it
writeTo(target, content);
}
The fallback is exactly the corruption path. The error handling made the code less safe, and it only triggers on the platform most users are on. Worse: it triggers precisely when another handle exists, which is exactly when a failure is most likely.
I hit this building an xlsx editor plugin for JetBrains IDEs. The plugin holds a workbook open for as long as the editor tab is open, which is the exact condition that makes the atomic move fail on Windows. The "obvious" fallback would have reintroduced the bug I was trying to avoid.
The fix was to guarantee the handle is fully closed before the move, and to let the save fail loudly rather than silently degrade.
The three silent failures
Not all file corruption crashes. Two of them are worse because nobody reports them.
Failure one: the truncated write. Described above. The file does not open at all, or opens as garbage. Loud, at least.
Failure two: the format wipe. The tool reads the file into a generic representation, changes one value, and serializes the whole thing back. Every byte of the file is rewritten from a model that only understands values. Column widths, number formats, embedded objects, comments — whatever the model does not represent — come back as defaults.
The data is intact. The tool reports success. The user opens the file and finds their carefully formatted report is now 64-pixel columns and no colors. Most will not file a bug; they will just stop using the tool. This is a silent 1-star review that never reaches your issue tracker.
Failure three: the structural inconsistency. The file is a container with internal references (in OPC/zip-based formats, an XML part points at another by relationship ID). If you rewrite one part and not the index, you get a file that opens, displays the right values, and still fails validation — either immediately in strict readers, or weeks later when something recalculates.
"It opened fine" is not a test. Three of these four failure modes produce a file that opens fine.
The pattern that actually works
It is four steps and it has not changed in thirty years:
1. write the new content to <file>.tmp
2. flush and close the handle
3. copy <file> to <file>.bak
4. atomically replace <file> with <file>.tmp
The order matters and step 2 is the one people skip. If the temp handle is still open, step 4 falls back to a non-atomic path on Windows. Flushing is not enough — the handle must be closed.
Step 3 is cheap insurance and it is what turns a catastrophic failure into an annoyance. A .bak next to the file costs one copy operation and means the user has a recovery path that does not depend on you.
Two details that matter in practice:
The temp file must live on the same filesystem. An atomic move only works within one volume. If you write the temp file to the system temp directory and the target lives on another drive, the move silently becomes a copy-then-delete — which is not atomic and reintroduces exactly the failure you were avoiding. This is easy to get wrong because Files.createTempFile() with no arguments puts the file in the OS temp directory, and on a machine with a second drive or a network share the target is often elsewhere. Create the temp file next to the target instead: <file>.tmp, not /tmp/something.
Flushing the temp file is not the same as closing it. A flush pushes bytes from your buffer to the OS; it does not release the file handle. On Windows, an open handle on the target blocks the replace, and an open handle on the temp file can block the rename on some filesystems. Close both, explicitly, before moving. In managed languages this means not relying on a garbage collector or a use block whose scope you have not traced.
If step 4 fails, do not fall back. Leave the temp file and report an actionable error. A failed save that tells the user "close the file in Excel and retry" is infinitely better than a silent in-place write that destroys the original.
Never write to the file you are reading. This sounds obvious and it is violated constantly, because reading and writing the same path is convenient and the failure only shows up under interruption.
How to verify a save path without waiting for a crash
You cannot easily test "the process dies mid-write" in a unit test. But you can check the properties that make it safe, and they are all observable:
- Is a
.tmpor.bakfile created next to the target? If not, the write is in-place and unsafe. - Does the file's modification time change atomically, or does it get progressively updated? Watch it during a large save.
- If you make the target read-only (or open it in another program), does the save fail cleanly, or does it overwrite anyway?
- Does the saved file still look right in the app that owns the format — not just in your tool?
That last one is the test most people miss. A file written by your tool and reopened by your tool proves nothing, because both share the same parser. Open it in the application the format belongs to, and you learn whether you wiped formatting, broke relationships, or silently re-encoded something.
Why this matters more for developer tools
For an app whose only job is editing one file, corruption costs the user one document. For a developer tool operating on files in a repository, the blast radius is different: those files are fixtures, test data, seed data, and config that other people depend on. A corrupted fixture gets committed and breaks someone else's build next week.
That asymmetry is why I think file-writing code deserves the same review attention as authentication or concurrency, and why it rarely gets it. It is four lines. It looks like plumbing. And the failures it produces are invisible until they are expensive.
The habit worth building is small: when you review a save path, ask what the file looks like at every possible interruption point. If the answer is "some of the new, none of the old", the code is wrong no matter how green the tests are.
Where to read more
- Java NIO
Files.move— theATOMIC_MOVEguarantee and when it is not honoured -
ECMA-376 — the OPC package model behind
.xlsx,.docxand friends — useful if you need to know which parts a "format wipe" destroys - Microsoft — Repair a corrupted workbook — what users are told to do when this goes wrong, which is usually "lose your formatting"
If you write tools that touch files, the two questions that catch most of this: does the save go through a temp file, and is there a backup if it fails? Curious whether anyone has hit the "temp file on a different drive" variant — that one took me a while to spot.
Top comments (0)