> 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/reference/common-issues.md).

# Common Issues

Fixes for the problems people hit most often.

***

## 1. Interaction Blocked (Cannot Build or Modify World)

**Symptoms**: Players receive click cancellation or block break/place restrictions inside a world.

### Checklist & Resolutions

* **World Status Set to Archive**: Archived worlds, and worlds with any other status that turns building off, block all modification unless the player holds the `buildsystem.bypass.archive` bypass node.
* **Builder Mode Active**: If the builders feature is enabled (`/worlds edit`), only registered builders can modify the world. Add builders using `/worlds addBuilder <player>` (requires creator role) or bypass via the `buildsystem.bypass.builders` permission.
* **World Protection Toggles**: Block breaking, block placement and block interactions can each be switched off per world in `/worlds edit`. `buildsystem.bypass.settings` overrides them and the builder list.
* **Build Mode**: `/build` (`buildsystem.build`) puts a player in build mode, which bypasses all of the above. Players do not need it to build where they are allowed to.
* **Administrative Bypass**: Players with `buildsystem.admin` bypass all restrictions.

***

## 2. Encoding Failures (Weird Characters in Chat/Menus)

**Symptoms**: Special characters or color codes in `messages.yml` display as garbled characters (e.g. `Â§` instead of color codes).

### Resolution

Enforce UTF-8 file reading in your server startup flags. Append the following argument to your Java execution command:

```bash
-Dfile.encoding=UTF-8
```

Example startup script:

```bash
java -Xms4G -Xmx4G -Dfile.encoding=UTF-8 -jar paper.jar nogui
```

Below is an example of garbled console text resolving from incorrect encoding: ![Encoding Error Example](https://content.gitbook.com/content/ZtdJcIoBgnlLEZoCMTDD/blobs/mUD0S3e8rWs8xKLSLPOw/156459998-25b69465-8cb7-47ad-960e-51b0edbea475.png)

***

## 3. World Fails to Import

**Symptoms**: Command `/worlds import <name>` reports failure.

### Resolution

* **Unsupported Data Version**: If a world was loaded or generated in a newer Minecraft version than the current server jar, BuildSystem refuses the import (`worlds_import_newer_version`). To force-load, start the server with `-DPaper.ignoreWorldDataVersion=true`, which BuildSystem honours too (caution: can lead to chunk errors).
* **Missing Custom Generators**: If the target world was generated using a custom chunk generator (e.g. CleanroomGenerator, VoidGen), the generator plugin **must** be loaded and active on the server before importing.
* **Invalid Name Characters**: Ensure the folder name does not violate the invalid characters regex defined under `world.invalid-characters` in `config.yml`.

***

## 4. "Is Busy" or "Could Not Be Unloaded"

**Symptoms**: Deleting, renaming, unimporting, restoring, backing up, downloading or saving a world as a template, or teleporting into it, is refused with `worlds_world_busy` or `worlds_world_unload_failed`.

### Resolution

* **Busy**: Only one of these operations runs on a world at a time, so the world folder is never changed by two of them at once. Wait for the other one, for example a backup upload or a download being packed, to finish and try again. The automatic backup skips a busy world and tries again later.
* **Could not be unloaded**: The world has to be unloaded before its folder is deleted, moved or replaced. If another plugin cancels `BuildWorldUnloadEvent`, or the server refuses to unload the world, nothing is changed and players who were moved out are sent back. The server's main world can never be unloaded, so these operations are refused for it straight away.

***

## 5. World Will Not Load After a Restore

**Symptoms**: Teleporting into a world is refused with `worlds_world_restore_failed`, and the console warns that a folder "is left from an earlier restore".

### Resolution

A backup restore failed and the old world could not be put back, so BuildSystem will not load the world, because loading it would generate a new one in its place. Restarting the server tries to put the old world back first. If that does not help, look in the `.buildsystem-restore` folder next to the world folder (or inside it, for a world folder that is a mount point or a symbolic link). The old world is in the folder whose name ends in `replaced`. Keep whichever copy you want as the world folder and delete the rest of `.buildsystem-restore`.

***

## 6. A Data File Could Not Be Read

**Symptoms**: The console reports that `worlds.yml`, `folders.yml`, `players.yml` or another BuildSystem file failed to load, or that BuildSystem is "not saving" one of them.

### Resolution

A file with a YAML error is never saved over. BuildSystem keeps a copy next to it as `<file>.broken-<timestamp>`, names the file in the error, and refuses every save to it. For `worlds.yml`, `folders.yml` and `players.yml` the plugin keeps running, but changes to that file are not kept, and players are not put into archive mode while their player data cannot be saved. Fix the YAML error and restart the server.

Some files stop BuildSystem from starting instead, with an error that names the file:

* **`statuses.yml` or `categories.yml`**: Fix the YAML error, or delete the file to start over with the built-in entries, then restart.
* **`config.yml`**: Fix the syntax error and restart. The file is not reset. `/config reload` on a broken file keeps the settings in use (`config_reload_invalid`).
* **A database** that cannot be reached, or an invalid `storage` block for the type in use. See [Data Storage](https://buildsystem.eintosti.de/getting-started/storage.md#when-something-goes-wrong).
