Skip to main content

Backing Up Vintage Story Safely

What this is about

On the Backups tab for a Vintage Story server, you may see a warning that it is unsafe to back up while the server is running. This article explains why that happens, what can go wrong, and why ZFS-enabled nodes don't have this problem.

You'll only see this warning on nodes that don't use ZFS. If your node uses ZFS, backups are already safe to take at any time — see the related article on ZFS backups.

How Vintage Story stores your world

A Vintage Story savegame is a database file (a .vcdbs file, which is an SQLite database). While the server is running, the game is constantly writing to it:

  • Autosave runs on a timer (every few minutes by default).
  • Chunks are written as players explore and as the world is loaded and unloaded.
  • Alongside the main database file, the database keeps a journal / write-ahead log so it can safely commit changes.

The important detail is that a single save is not one instantaneous write. It's a sequence of writes spread across the main database file and its journal, and at any given moment some of those writes may be only partially applied.

Why backing up while running can corrupt the save

A normal (non-ZFS) backup works by copying files off the disk one at a time. If the server is running while that copy happens:

  1. The backup may copy the savegame database mid-write, capturing a half-finished transaction (a "torn" write).
  2. The main database file and its journal are copied at different moments, so they no longer agree with each other.
  3. The result is a backup whose database is in a state that never actually existed on the live server.

When you later try to restore that backup, the database engine may refuse to open it, roll back to an older state, or load with missing or damaged recent progress. In the worst case the world is unrecoverable.

This is why, on a non-ZFS node, the safe procedure is:

  1. Stop the server (this flushes everything to disk and closes the database cleanly).
  2. Create the backup.
  3. Start the server again.

Why ZFS fixes this

A ZFS snapshot is atomic: it captures the entire filesystem — the savegame database and its journal — at the exact same instant. There is no window where some files are newer than others.

The state captured by a ZFS snapshot is a crash-consistent image: it looks exactly like the disk would look if the machine had lost power at that moment. SQLite (the database Vintage Story uses) is specifically designed to recover cleanly from that situation using its journal — the same way it recovers after a power loss. So even though the server was running, the restored world opens correctly and loses, at most, a few seconds of activity rather than becoming corrupt.

In short:

  • Non-ZFS node: stop the server before backing up, or risk a corrupt save.
  • ZFS node: snapshots are atomic and crash-consistent, so you can back up safely at any time without stopping the server.

SuHosting is progressively migrating all nodes to ZFS so that every Vintage Story server can be backed up safely without downtime. See the ZFS backups article for more on that migration.

Back to top