Minecraft world backup and restore

A Minecraft server backup is the world folders - world, world_nether and world_the_end on Paper, or one world folder on vanilla and Fabric - plus a handful of files beside them: server.properties, the op, whitelist and ban lists, and the plugins/ or config/ folder. To make the copy consistent, run save-off, then save-all flush, take the copy, then save-on. To restore everything, stop the server and put the folders back. To roll back one area, replace only the matching region files; to roll back one player, replace their file in playerdata/. This post covers each of those, with the arithmetic for finding the right region file and the mistakes that turn a restore into a second disaster.

What a Minecraft world is on disk#

The world is not one file. It is a folder of many, and knowing which file holds what is the difference between restoring a griefed village and restoring the entire server to last Tuesday.

Paper and every Bukkit-derived server split the three dimensions into three top-level folders. Vanilla, Fabric, Forge and NeoForge keep them all inside one. The name world comes from level-name in server.properties.

Inside each dimension, three folders hold chunk data in the same region-file format:

• `region/` - blocks, block entities such as chests and furnaces, and biomes. The terrain itself.
• `entities/` - since 1.17, mobs, animals, item frames, armour stands, minecarts and dropped items live here instead of in the terrain files.
• `poi/` - points of interest: villager workstations, beds, bee nests, portals. Villagers use this to find jobs and homes.

And at the top of the main world folder:

• `level.dat` holds the seed, the spawn point, the game rules, the world border, the time and the data pack list. level.dat_old is the previous copy, written each time level.dat is saved.
• `playerdata/<uuid>.dat` holds each player's inventory, ender chest, position, health and experience. Only the main world has this folder, even on Paper.
• `advancements/` and `stats/` hold per-player JSON.
• `data/` holds maps (map_*.dat), raids, the scoreboard and command storage.
• `datapacks/` holds the world's data packs.

A world that has been played for a year is mostly region/ by size. Everything else is small and, apart from playerdata/, rarely interesting on its own.

Everything else that belongs in the backup#

A restored world next to a fresh server directory is not a working server. The rest of the server root matters too:

Plugin data deserves a sentence of its own. Claim plugins, permissions and economies often keep their state in a local database file inside plugins/ - LuckPerms and CoreProtect both do by default. A world restored without the matching plugin data gives players their builds back without their claims, or their claims without their builds. Back them up together and restore them together.

The things you can leave out: logs/ (useful but not part of the state), cache/, libraries/, versions/, and the server jar, all of which can be downloaded again. Leaving them out makes backups smaller and faster.

Making a consistent copy#

The server does not write the world continuously. Chunks live in memory and are written to their region files during autosaves and when they unload. If you copy the folder while that is happening, you can capture a region file halfway through being written, or level.dat from one moment and the region files from another.

The fix is three console commands:

save-offsave-all flush... take the copy ...save-on

save-off stops automatic saving. save-all flush writes everything in memory to disk and does not return until the write has finished. The copy taken after that is a consistent snapshot. save-on resumes normal saving; forgetting it leaves the server running with nothing written to disk until the next restart, so if you script this, make sure save-on runs even when the copy fails.

On your own machine, a backup can be as simple as:

$ tar -czf backups/world-$(date +%F-%H%M).tar.gz \    world world_nether world_the_end plugins server.properties \    ops.json whitelist.json banned-players.json banned-ips.json

Run it between save-all flush and save-on, and copy the archive somewhere that is not the same disk - a backup on the disk it protects covers a corrupt chunk and nothing else. Backups that actually restore covers where copies should live and how many to keep.

On a panel the same sequence becomes a schedule. On RE:NODE, the Schedules tab runs ordered tasks on a cron expression, so one schedule can send save-off, then save-all flush, wait, take a backup, and send save-on. Backup slots are included on every Minecraft plan, stored off the machine they protect, and downloadable, and you can lock one so rotation does not remove it. Scheduled tasks worth having has a full timing table for this.

Restoring the whole world#

Restoring everything is the simplest restore and the one people get wrong under pressure.

1. Stop the server and wait for it to finish shutting down.
2. Keep the current state. Rename world to world-broken (and the Nether and End folders) or take a fresh backup of it. The current world may contain hours of legitimate progress you will want to salvage, and it is evidence if you are dealing with a griefer.
3. Put the backup's folders in place, with the exact same names. On Paper that is three folders; on vanilla it is one.
4. Restore the matching plugin data from the same backup if claims, permissions or economy have changed since.
5. Start the server and read the log. Preparing level "world" and no warnings about missing chunks means it loaded.
6. Log in and check all three dimensions. A new, empty Nether means the Nether folder is in the wrong place or has the wrong name - your data is still there under the other name.

On RE:NODE, restoring a backup is a button in the panel. The same discipline applies: if the current state might be worth keeping, take a backup of it first. Deleting a server deletes its backups, locked ones included, so keep a downloaded copy of anything you cannot afford to lose before cancelling or reinstalling.

Rolling back one area#

Restoring the whole world to fix one griefed base throws away everybody else's progress. Region files let you restore just the area that was damaged.

Each region file covers 32 by 32 chunks, which is 512 by 512 blocks, and is named after its region coordinates: r.<x>.<z>.mca. To find which file holds a block position, divide by 512 and round down:

region x = floor(block x / 512)region z = floor(block z / 512)Block (1200, -300)  ->  r.2.-1.mcaBlock (-40, 700)    ->  r.-1.1.mcaBlock (511, 512)    ->  r.0.1.mca

Rounding down matters for negative numbers: block -40 is in region -1, not region 0. A base near a region boundary spans two or four files.

The procedure:

1. Note the coordinates of the damaged area from F3, and work out every region file it touches.
2. Stop the server.
3. From the backup, copy those files from region/, and the files with the same names from entities/ and poi/, over the live ones in the right dimension's folder.
4. Start the server and check the area.

Copying only region/ is the classic mistake. On 1.17 and later the terrain comes back but the entities do not match: item frames and armour stands vanish or duplicate, animals are missing, villagers lose their workstations because poi/ still describes the griefed state.

Region files are coarse - 512 blocks is a lot of other people's builds. For anything smaller, MCA Selector is the standard tool. It opens a world on your own computer, shows the map, and lets you select individual chunks to delete or to import from another copy of the world. The workflow is to download the backup and the current world, use MCA Selector to bring the damaged chunks from the backup into a copy of the current world, then upload the result with the server stopped.

If the damage is griefing rather than corruption, a block-logging plugin is usually a better tool than any backup, because it undoes one person's actions and keeps everybody else's. CoreProtect's rollback by user, radius and time is covered in grief protection and anti-cheat. Backups are for what a logging plugin cannot see: corruption, a bad plugin, a mistaken command, or a mod that ate a chunk.

Restoring one player#

Lost inventories are the most common restore request, and they never need a world rollback.

1. Find the player's UUID. usercache.json in the server root maps recent names to UUIDs, and on an online-mode server the UUID is the same one shown on any Minecraft profile lookup.
2. Make sure the player is offline. The server writes their file when they log out and will overwrite yours if they are online.
3. Copy world/playerdata/<uuid>.dat from the backup over the live file. Copy advancements/<uuid>.json and stats/<uuid>.json too if those matter.
4. Have the player log in.

The player file holds position as well as inventory, so a restored player appears where they were when the backup was taken. Tell them, or they will report a teleport bug. Ender chest contents are in the same file and roll back with it.

When level.dat is damaged#

If the server refuses to load a world with an error about level.dat, or loads it with the wrong seed, spawn or game rules, the file is likely damaged - usually by a kill during a save. Because level.dat_old is the previous copy:

1. Stop the server.
2. Rename level.dat to level.dat_broken.
3. Copy level.dat_old to level.dat.
4. Start the server.

If both are damaged, restore level.dat alone from a backup. It holds world-wide state, not terrain, so an older copy costs very little: the time of day, the world border and recent game rule changes may revert.

This is also why a clean stop matters. On RE:NODE the Stop and Restart buttons send a clean stop, which saves first. A container that reaches its memory limit is stopped and restarted clean rather than left to swap, which protects the machine but is not a save - everything since the last autosave is lost. Keeping memory headroom is part of keeping the world safe.

Testing a backup before you need it#

A backup you have never restored is a guess. The cheapest test takes ten minutes:

1. Download a recent backup.
2. Unpack it on your own computer next to the same server jar and Java version.
3. Start it locally and connect to localhost.
4. Walk to a recent build, open a chest, check the Nether.

If that works, the backup works. If it does not, you have found out on a quiet day rather than during an outage. Testing a restore before you need it turns this into a routine.

A reasonable schedule for an active server:

FAQ#

Can I back up a Minecraft world while the server is running?

Yes, if you run save-off and save-all flush first and save-on afterwards. The flush writes everything to disk and holds further writes while you copy. Copying without it can capture region files mid-write.

How do I roll back just one area of the world?

Work out which region files cover it - divide block coordinates by 512 and round down - then, with the server stopped, copy those files from the backup's region/, entities/ and poi/ folders over the live ones. For areas smaller than a region, use MCA Selector to import individual chunks.

How do I restore one player's inventory?

With the player offline and the server running or stopped, replace world/playerdata/<uuid>.dat with the copy from the backup. The UUID is in usercache.json. The player will also be moved to where they stood when the backup was taken.

Why is the Nether empty after a restore?

The Nether folder is in the wrong place for your server software. Paper uses world_nether/DIM-1/region, vanilla and Fabric use world/DIM-1/region. The server generated a new Nether because it found nothing where it looked.

Are backup plugins a good idea?

Usually not on their own. A plugin writes its archives to the same disk as the world, which protects against a corrupt chunk and nothing larger. Use backups stored off the machine, and if you want a plugin at all, use it for its scheduling around save-all flush, not as the only copy.