# troubleshooting

## Quick checks

Run these first:

```
/pb info
/pbadmin license
/pbadmin help
```

Then check the console during startup and while reproducing the problem.

## Common issues

| Problem                                          | Likely cause                                                                     | Fix                                                                             |
| ------------------------------------------------ | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Commands work but features are locked            | License missing/invalid                                                          | Run `/pbadmin license set <key>` or contact support privately.                  |
| Bot cannot spawn                                 | Citizens not ready, disabled world, missing permission, or invalid runtime state | Check `/pb info`, `default.disabled-worlds`, and permissions.                   |
| `/spawnbot` opens nothing                        | Player lacks spawn permission or license is locked                               | Grant `practicebot.spawn.normal`/`practicebot.spawn.cpvp` and verify license.   |
| Template spawn fails                             | Template missing, target binding mismatch, invalid world/coordinates             | Check `/pbadmin template spawn` syntax and `bot_templates.yml`.                 |
| GUI item is missing or broken                    | Invalid material, duplicate slot, invalid YAML                                   | Validate the GUI file and use valid Bukkit material names.                      |
| Placeholder returns literal text                 | PlaceholderAPI missing or not loaded                                             | Install PlaceholderAPI and restart.                                             |
| CPvP bots hurt TPS at high counts                | Too many active CPvP bots or aggressive scan values                              | Keep `cpvp.performance.adaptive-enabled` true and reduce bot count for testing. |
| Crystal/anchor behavior looks wrong in one arena | Arena geometry or template profile mismatch                                      | Test in a clean arena, then tune template CPvP settings.                        |

## YAML validation checklist

* Use spaces, not tabs.
* Keep indentation consistent.
* Quote text containing `:` when needed.
* Use valid Bukkit material names.
* Do not duplicate important keys in the same section.
* Back up before editing.

## Safe reload procedure

```
/pbadmin reload
```

Reloads:

* main config
* messages
* GUI configs
* templates

If a file is badly broken, stop the server, restore backup, and start again.

## Support checklist

When requesting support, provide:

* PracticeBot version
* Paper version
* Citizens version
* Java version
* relevant config section
* exact command used
* exact error message
* short video/GIF if behavior-related

Do not provide:

* full license code
* private server IP if not needed
* private file system paths
* private source/build artifacts

> **Media placeholder:** Add a short troubleshooting video example: command used, visible result, and console message with private data blurred.


---

# Agent Instructions: 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://edelweiss-network.gitbook.io/practicebot/troubleshooting.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.