If a machine's configuration file breaks: where the old copy lives

Every virtual machine and every container has a small text file. How many cores, how much memory, which disk, which network: it is all in there, written in a form a human can read.

What happens if that file breaks, where is the old copy, and what should you watch out for if you edit it by hand?

First the good news: a broken file only affects its own machine

Every machine has its own separate file. A typo in one does not bring down the panel, does not stop the other machines, does not affect the server.

The symptom is usually this: that machine stops appearing in the list, or refuses to start. Everything else keeps working normally. Know this before you panic, because the first impression is usually "the system is broken" and it is not.

How it breaks

Editing by hand. This is the most common cause. A comma, a quote, a mistyped key name.

Editing while the machine is running. Even if the file does not break, something you did not expect happens: your change takes effect at the next start while you assume it took effect immediately. Or the system updates the file itself and writes over what you wrote.

A write interrupted midway. The power cuts out, the disk fills up, the process is killed. The file is left half done.

That third one is the sneakiest and deserves its own heading.

A half-written file is worse than no file at all

If a file is absent, that is an obvious state. A program looks, does not find it, says "not there" and carries on with defaults. That state is easy to handle.

A half-written file is not like that. It looks like a file. The program checks whether it exists, finds it, trusts it, and tries to work with the incomplete data inside. The trouble shows up not at the moment of reading, but afterwards.

The fix is simple and applies to every write: do not overwrite the file directly. Write to a temporary name first, then move it into place. A move either happens completely or not at all; there is no in between. That way the file's contents are either the old ones or the new ones, never half.

If you are writing a script that touches Proxmox configuration, that single habit is worth more than the rest of the code you will write.

The old copy lives in two places

Inside the backup. A machine's backup carries not only the disk but the configuration file as it was at that moment. When you restore the backup, the configuration comes back too. Most people think of a backup as data only, and never realise they are holding a recovery path.

Inside the snapshot. When you take a snapshot, the configuration at that moment is written into a named section of the same file. So the file carries part of its own history inside it.

But these two do not substitute for each other, and the difference matters: the snapshot's record sits inside the same file. If the file itself is destroyed, that record goes with it. A backup is somewhere else. The real recovery path is the backup; a snapshot is just a point you might want to return to.

If you are going to edit by hand

Stop the machine first.

Take a copy before you edit, and put that copy somewhere else. The place configuration lives was designed for configuration; do not leave backups there.

After making the change, start the machine and see that it actually works. Do not leave it until the next restart and forget; a forgotten half-finished edit comes back months later as a fault nobody connects to anything.

The general rule: "file missing" and "file broken" are separate states

A program's recovery path is usually written with the "file missing" state in mind, because that is the one that comes to mind first. The "file exists but its contents are broken" state does not come to mind.

Yet the second is the genuinely dangerous one, precisely because it was not thought about. And the two look different: a missing file carries a marker, broken content does not.

What Atlas does

Atlas keeps a few small settings files of its own, and there are several things worth telling honestly here, because all of them were found by measuring.

Two sibling files were behaving differently. One repaired itself when its file was corrupt: it moved the broken one aside and started clean. The other did not: it raised an error and stopped there, meaning that feature became permanently unusable with no way for the user to fix it through the product.

The cause was exactly the rule above: the recovery branch was written for the "file missing" state. A broken-content error does not carry that marker, so the branch did not catch it and the error escaped upward.

The quarantined copies were never cleaned up. Every corruption event left a permanent file, with no cap on how many. Measured on a live machine: two of them had been sitting there for months. This is the same rule written elsewhere in this wiki: everything that writes needs a ceiling.

Two quarantines in the same instant produced the same name and the second copy overwrote the first, so a broken version disappeared silently.

All of them were fixed, and one rule was placed on the quarantine step itself: it never raises an error, under any circumstances. Quarantine is a recovery step, and a recovery step must not become a new source of failure. That sentence looks small, but it is the one anybody writing recovery code should pin to the wall.