> 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/v4/getting-started/common-issues.md).

# Common Issues

Solutions to common configuration, permission, and runtime errors in BuildSystem.

***

## 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 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.
* **Global Build Mode**: Ensure the player has toggled build mode active via `/build`.
* **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](/files/DHnkIIP4aSRb5TmIuoLH)

***

## 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, Bukkit will block the import. To force-load, Paper servers can specify `-DPaper.ignoreWorldDataVersion=true` in their startup arguments (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`.