> For the complete documentation index, see [llms.txt](https://buildsystem.eintosti.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://buildsystem.eintosti.de/managing-worlds/world-backups.md).

# World Backups

Schedule backups to disk, S3, or SFTP, and restore them.

BuildSystem includes a backup subsystem. Backups copy region files and world configurations, sending them to local or remote storage drivers.

***

## Backup Scheduling

### Automatic Backups

If configured in `config.yml` (`world.backup.auto-backup.enabled`), backups run on a recurring schedule.

* **Interval**: Set in seconds via `interval` (e.g., `900` for 15 minutes).
* **Active World Filtering**: If `only-active-worlds` is set to `true`, a world's timer only advances while a player who may build in it is there.
* **Busy Worlds**: A world that is busy with another operation, such as a rename or a restore, is skipped and backed up on a later round.

### Manual Backups

Administrators or builders can force an immediate backup of their current world:

* **Command**: `/worlds backup create`
* **Permission**: `buildsystem.backup.create`

***

## Viewing & Restoring Backups

To view the history of backups for the current world:

* **Command**: `/worlds backup`
* **Permission**: `buildsystem.backup`, with the `.self` and `.other` suffixes for your own and other players' worlds. `buildsystem.admin` bypasses it.

![World Backups List](https://2366875379-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZtdJcIoBgnlLEZoCMTDD%2Fuploads%2Fgit-blob-418e42d4cffac617754e2c80079705f1b79f25da%2Fworld-backups_list.png?alt=media)

### Restoration

1. Open the backups list (`/worlds backup`).
2. Click on the target backup item (named with the timestamp of creation).
3. Confirm the restoration prompt.

The backup is downloaded, checked and extracted in the background while the world stays loaded, so a broken archive is refused before anything happens to the world. Only taking the world offline runs on the main thread. The extracted backup then takes the world's place by renaming folders, and the world is loaded again with its players back in it. A world folder that is a mount point (such as a per-world Docker volume) or a symbolic link cannot be renamed, so its contents are swapped inside it instead. While a restore runs, the disk needs room for one extra copy of the world.

If the swap fails, the old world is put back, loaded, and its players return. In the rare case the old world cannot be put back either, it stays unloaded and refuses to load (`worlds_world_restore_failed`) until an admin has fixed its folder; the console names the `.buildsystem-restore/<world>.replaced` folder that holds the old copy. A restore interrupted by a server stop is undone at the next start, before any world loads.

{% hint style="danger" %}
A restore that succeeds replaces the current world, and there is no undo. Take a manual backup first if the current state matters at all.
{% endhint %}

{% hint style="info" %}
**The server's primary world cannot be restored in place, and BuildSystem refuses to try.** Since Paper 26.1 every other world lives inside the primary world's folder, under `dimensions/minecraft`, so wiping that folder would delete every world on the server. Bukkit also refuses to unload the primary world, so the unload that is supposed to precede the wipe would silently do nothing.

To roll the primary world back, stop the server and extract its archive by hand.
{% endhint %}

### Creating a Backup Manually

* **Command**: `/worlds backup create`
* **Permission**: `buildsystem.backup.create`

Backups of one world run one at a time. Asking for a second while the first is still uploading queues it rather than running both, so the retention limit set by `world.backup.max-backups-per-world` cannot be overshot by two backups racing each other. A new backup is stored before the oldest ones are trimmed, so a failed backup never costs you an old one; for a moment after a backup there is one archive more than the limit. Local backups are dated by the timestamp in their file name, so copying or syncing the backups folder does not change which ones count as the oldest.

While the world is busy with another operation, such as a rename, an unimport or a download being packed, backups and restores are refused with `worlds_world_busy`.

{% hint style="info" %}
The world is saved to disk when the backup's turn starts, so a backup waiting behind a slow S3 or SFTP upload reflects the world as of that moment, not as of when it was queued. On Paper the save also waits for the chunk writer to finish. The world's autosave then stays paused until the archive is stored, so region files cannot change while they are being read.
{% endhint %}
