A corrupted .xlsx file is almost never the result of a bad library. It is the result of a save operation that was interrupted, or a write that replaced more of the file than it needed to. The distinction matters, because the first is a design flaw you can detect in advance and the second is a silent one you usually discover days later.

If you have ever installed a spreadsheet plugin, opened a workbook, changed one cell, and found the file unopenable afterwards, you have hit one of the three failure modes below. All three are avoidable, and none of them require the plugin to be malicious — just careless about a file format that punishes carelessness.

The format that makes corruption easy

An .xlsx file is a zip archive. Inside it there is a shared strings table, one XML part per worksheet, a styles part, and — critically — a _rels directory that records how all those parts reference each other.

That last piece is what separates a spreadsheet from a text file. Excel does not store "cell A1 contains 12". It stores a cell whose value lives in one place, whose style index points into a styles table, and whose worksheet is declared in a relationship file. Every one of those pointers has to stay consistent.

A tool that reads the whole workbook, changes one value, and writes a fresh package from scratch has to rebuild all of those relationships correctly. Most library code does this well. The problem is not correctness in the happy path — it is what happens when the process dies halfway through writing.

Failure mode one: the truncated write

This is the most common and the most destructive. The tool opens the original file for writing, then streams the new workbook into it.

If anything interrupts that stream — the IDE is closed, the process is killed, the disk fills, the machine sleeps — the file is left partially written. On disk it may still look like a valid .xlsx by extension, but the zip central directory is missing or the XML is cut mid-element. Excel reports it as corrupt and offers to repair it, which usually means recovering the values and losing the formatting.

The fix is well known and cheap: never write to the file you are reading. Write to a temporary file next to it, then move the temporary file over the original in one operation. A file move is atomic on the same filesystem, so a reader either sees the old complete file or the new complete file, never a half-written one.

Failure mode two: the formatting wipe

Less dramatic, more common, and harder to notice. The values survive; everything else does not.

When a tool reconstructs the package from a generic representation, it has to decide what to do with column widths, fills, borders, number formats, frozen panes, merged ranges, and conditional formatting. If the tool only cares about cell values, all of that comes back as defaults.

The tell is visual: your carefully sized columns are now uniform, header rows lost their fill, and dates render as raw serial numbers. The data is intact, so nobody files a bug — they just quietly stop using the tool.

This is not a crash. It is a fidelity decision made implicitly by whoever wrote the writer. A tool that rewrites only the cells you changed leaves the rest of the package untouched, and this failure mode does not happen at all.

Failure mode three: the broken relationship

The subtle one. The workbook opens, but Excel complains about a repaired record, or a sheet is missing, or formulas that referenced an external link now show #REF!.

This happens when a tool edits one XML part without updating the corresponding relationship entry, or when it strips a part it did not understand — a chart definition, a pivot cache, a VBA project in an .xlsm file. The package is still a valid zip. It is just inconsistent with itself.

This is why "it opened fine" is not a sufficient test. A file can open, display your values, and still be structurally wrong in ways that only surface when Excel tries to recalculate or when another program reads it.

How to tell whether a tool is safe before you trust it

There is one question that separates careful tools from careless ones, and you can usually answer it from the documentation:

When this tool saves, does it write to a temporary file and replace, or does it write in place?

If the documentation does not say, assume the worse option. The safe pattern costs one extra file write and is trivial to describe, so a tool that does it will usually mention it — and a tool that overwrites silently has no reason to advertise the fact.

Three supporting questions worth asking:

Does it keep a backup? A .bak next to the original costs nothing and turns a catastrophic failure into an inconvenience.

Does it claim file types you did not ask for? Several plugins register for .csv on install. That is a separate risk — the association often survives uninstalling the plugin — and it is a signal that the tool is willing to take over more of your filesystem than you agreed to.

Does it tell you what it cannot do? A tool that states its limits — row caps, no formula editing, formatting preserved but not editable — has thought about the boundary between what it touches and what it leaves alone. That is the same discipline that produces safe saves.

The verification habit that catches everything

If you already have a tool you are unsure about, there is a two-minute test.

  1. Copy a workbook you care about to a scratch directory.
  2. Open the copy, change one cell, save.
  3. Open it again from a fresh process — not the tab you already have open.
  4. Check the .bak exists and the columns still look the way they did.

Step three matters because the editor was holding a parsed representation, not the file. Reopening forces a real read from disk. Step four catches the formatting wipe, which a value-based check will miss.

If both pass, the tool is probably careful. If the file fails to open but the .bak opens fine, you have found a truncating writer and you should stop using it on anything you cannot regenerate.

What a safe writer looks like from the inside

For the record, the sequence that avoids all three failure modes is short:

1. copy <file> to <file>.bak 2. write the new workbook to <file>.tmp 3. flush and close the tmp handle 4. atomically move <file>.tmp over <file>

On Windows there is one extra requirement that is easy to miss: the original file handle must be fully closed before step four, otherwise the atomic move fails and the code falls back to writing in place — reintroducing failure mode one. Libraries that keep the workbook open for the lifetime of the editor have to be careful here.

This is the pattern I used when building an xlsx editor for JetBrains IDEs. It is not a feature you can show in a screenshot, which is exactly why it is worth checking for.

FAQ

Can a corrupted xlsx be repaired?
Often, yes — values usually survive. Excel's Open and Repair recovers cell contents but frequently drops formatting, and structural problems like broken chart references may not come back. If you kept a .bak, use that instead; recovery tools are a last resort, not a strategy.

Does this apply to .xls files too?
Yes, and worse. The legacy .xls format is a binary container rather than a zip, so the failure modes are less inspectable — a truncated .xls is much harder to recover than a truncated .xlsx. The same "write to temp, then move" rule applies.

Why did my file open fine but Excel says it needs repair?
That is failure mode three. Excel tolerates some inconsistencies on open and then reports them when it validates the package on save or recalculate. A structurally wrong file can look correct for weeks.

Is a plugin more likely to corrupt a file than a script?
Not inherently. Both use the same libraries. The difference is that a plugin holds the file open for as long as the tab is open, which is precisely the condition that makes an in-place write dangerous on Windows.

What if the tool only offers "Save" with no backup option?
Then test it on a copy first, and keep the original outside the project. A tool with no backup path is a tool whose failure mode you discover at the worst possible time.

Sources

Conclusion

Spreadsheet corruption is a save-path problem, not a parsing problem. The three ways it happens — truncated writes, reconstructed packages losing formatting, and inconsistent relationship entries — all stem from the same decision about how much of the file the tool rewrites.

You do not need to audit the code to judge a tool. Ask what it does when the save is interrupted, ask whether it keeps a backup, and test it on a copy before it touches anything you cannot regenerate. That is enough to separate the tools worth trusting from the ones that will eventually cost you an afternoon.