> 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`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://buildsystem.eintosti.de/v4/getting-started/common-issues.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.