> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poplock.scyne.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Restore

> Use the interactive restore menu to roll back worlds, configs, or the full server directory.

`serv restore` presents an interactive numbered menu listing every available archive. Selecting an entry stops the server (if running), creates an undo backup of whatever is about to be replaced, performs the restore, and restarts the server.

<Warning>
  Restoring overwrites current server files permanently (except for the automatic undo point that is created first). Always confirm which backup you are selecting before typing `y`.
</Warning>

<Tip>
  A restore undo point is created automatically before every restore — except when restoring the undo archive itself. If you make a mistake, run `serv restore` again and choose **Restore Undo** to reverse it.
</Tip>

***

## Running the restore menu

<Steps>
  <Step title="Open the restore menu">
    ```bash theme={null}
    serv restore
    ```

    The menu lists all archives found in `backups/`, grouped by type, with size and file count for each entry:

    ```text theme={null}
    Available Backups:
      [0] Daily Snapshot: 2026-04-04 23:30:01 (1.2G)
      [1] Daily Snapshot: 2026-04-03 23:30:02 (1.2G)
      [2] Full Backup: 20260402_143000 (2.8G)
      [3] Restore Undo (980M)
    ```
  </Step>

  <Step title="Enter the number of the backup to restore">
    Type the number shown in brackets and press Enter. Press Enter with no input to cancel without making any changes.
  </Step>

  <Step title="Confirm the restore">
    The menu prints a warning and asks for confirmation:

    ```text theme={null}
    WARNING: Restoring will OVERWRITE the current server files!
    Are you absolutely sure you want to restore 'Daily Snapshot: 2026-04-04 23:30:01'? [y/N]
    ```

    Type `y` and press Enter to proceed. Any other input cancels the restore.
  </Step>

  <Step title="Restore runs automatically">
    The command handles everything from this point:

    1. Stops the server if it is running
    2. Creates an undo backup of what is about to be replaced
    3. Wipes and cleanly extracts the selected archive
    4. Removes stale `session.lock` files
    5. Restarts the server if it was running before the restore
  </Step>
</Steps>

***

## Restore paths

The restore command behaves differently depending on which archive type you select.

### Daily snapshot restore

A daily snapshot contains world directories plus `whitelist.json` and `server.properties`. The restore process:

1. Inspects the archive to determine exactly which world directories and config files it contains.
2. Creates an undo backup of only those items — not the entire server directory.
3. **Wipes the existing world directories** before extracting. This is required to prevent stale chunk files and player data from after the snapshot date from surviving the restore.
4. Extracts the snapshot into the server directory.
5. Removes `session.lock` files from each restored world directory.

Config files (`whitelist.json`, `server.properties`) are overwritten in place rather than wiped, since they are single files with no stale-data risk.

### Full backup restore

A full backup contains the entire server directory. The restore process:

1. Creates a full undo backup of the current server directory (same exclusions as `serv backup`: no `backups/` folder, no build artifacts).
2. Extracts the full backup archive into the server directory.
3. Removes all `session.lock` files found up to two directory levels deep.

### Restore Undo

Restoring the undo archive reverses the most recent restore operation.

1. Peeks at the top-level entries in the undo archive to identify which directories it covers.
2. Removes those directories from the server directory.
3. Extracts the undo archive.
4. Removes any `session.lock` files from restored directories.

**No new undo point is created** when restoring the undo itself — the menu will warn you of this before you confirm.

***

## Server shutdown behavior

Before any restore begins, the server must be fully stopped. If the server does not shut down gracefully within 30 seconds of receiving the `stop` command, it is force-killed. If the process cannot be stopped even after a force-kill, the restore is aborted to prevent world corruption.

***

## Session lock files

After every restore, `session.lock` files are deleted from all restored world directories. These files are written by a running server instance to claim ownership of a world. If a `session.lock` from an archived server instance is left in place, the newly started server will refuse to load the world and log a "world locked" error.