> For the complete documentation index, see [llms.txt](https://docs.ohalee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ohalee.com/products/modern-bedwars/troubleshooting.md).

# Troubleshooting

Most first-run issues are a missing password or a Redis/MariaDB reachability problem. Work through the table before opening a support ticket.

<table><thead><tr><th width="330">Symptom</th><th>Likely cause</th></tr></thead><tbody><tr><td><code>list servers</code> in the service shell stays empty</td><td>A game server isn't registering — check its <code>server-id</code> matches the proxy's <code>gamePrefix</code> (<code>config.json</code>) and that it points at the same Redis as the service.</td></tr><tr><td>Players stuck in queue</td><td>No instance is reporting heartbeats; or <code>max-match-per-server</code> is <code>0</code>; or every instance is already at capacity.</td></tr><tr><td>Lobby/game plugin fails to enable with a DB error</td><td><code>config.yml</code> <code>password</code> is empty — set it.</td></tr><tr><td>GUIs render raw keys like <code>master.profile.title</code></td><td>The key is missing from the active language file. Copy it from <code>messages_en_US.properties</code>.</td></tr><tr><td>Tick lag on game servers under load</td><td>Raise the sidebar refresh interval in <code>defaults/scoreboard.yml</code> (refresh the scoreboard less often).</td></tr><tr><td>A node stops receiving messages</td><td>Different Redis instance, wrong Redis password, different <code>database:</code> index, or a network policy blocking port 6379.</td></tr></tbody></table>

## Log locations

* **Service:** `./logs/bedwars-service.log` (rotated daily, capped at 1 GB).
* **Bukkit plugins:** standard Paper console + `logs/latest.log`.

## Connectivity checks

Test Redis from a node:

```bash
redis-cli -h <redis-host> -p 6379 -a <password> ping
```

Test MariaDB from a node:

```bash
mysql -h <mariadb-host> -u bedwars -p bedwars -e "SELECT 1;"
```

## Start / stop order

* **Start:** service → proxy → lobby → game (brain up first so registrations succeed).
* **Stop:** game → lobby → proxy → service (brain down last so in-flight messages have somewhere to go).

## Upgrading a jar

1. Stop the affected node.
2. Replace the `Bedwars-<module>-1.0.jar` with the new build.
3. **Keep** your existing `config.yml` / `application.properties` / `mariadb.json` / `redis.json` / `config.json` and any edited `defaults/*.yml`.
4. Skim shipped defaults vs your copy for **new** keys and copy them in (the plugins don't auto-merge missing keys).
5. Start the node.