> For the complete documentation index, see [llms.txt](https://docs.cheddah-development.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cheddah-development.net/plugin-documentaion/better-baltop/troubleshooting.md).

# Troubleshooting

### Getting support

If this page does not solve the problem, open an issue on the [BetterBaltop issue tracker](https://github.com/Cheddah01/Better-Baltop/issues).

Please include:

* Your BetterBaltop version
* Your Paper and Java versions
* Your Vault and economy plugin versions
* Your PlayerPoints version, if installed
* The relevant console error or warning
* A short explanation of what happened and how to reproduce it

Do not include passwords, database credentials, private keys, or other sensitive information.

### BetterBaltop is disabled

If `/baltop` says the plugin is disabled, read the earlier BetterBaltop startup messages in the console.

The most common cause is:

```
Vault is loaded, but no economy provider is registered
```

Vault is only a bridge. Install or enable a Vault-compatible economy plugin, then fully restart the server.

### I do not appear on the leaderboard

Try these checks:

1. Confirm your economy account exists and has a balance.
2. Remember that exact zero balances are hidden by default.
3. Run `/bbt refresh economy`.
4. Wait for the refresh to finish.
5. Run `/bbt status` and check the entry count and state.

To display players with exactly zero, set:

```yaml
leaderboard:
  show-zero-balances: true
```

Then reload BetterBaltop or restart the server and request another refresh.

### PlayerPoints switch is missing

The switch appears only when the PlayerPoints hook succeeds.

1. Confirm PlayerPoints is installed and enabled.
2. Use PlayerPoints `3.3.5` or a compatible 3.x release.
3. Fully restart the server after installing it.
4. Check the console for the BetterBaltop PlayerPoints hook message.
5. Run `/bbt status`.

BetterBaltop intentionally hides the button when PlayerPoints is unavailable.

### Player heads use the default skin

Online players' current skins should appear immediately. Visible offline players are resolved asynchronously and may update shortly after the menu opens.

If heads remain unresolved:

* Wait a few seconds and reopen the menu.
* Confirm the server can reach Minecraft profile services.
* Check whether the server is using offline mode or a proxy configuration that changes player UUIDs.
* Look for profile or network errors in the console.

Failed skin lookups wait five minutes before trying again to prevent repeated requests.

### The leaderboard says unavailable or stale

Run `/bbt status` to identify the affected source.

* **Stale** means the last successful list is still being shown after a newer refresh failed.
* **Unavailable** means no refresh has completed successfully yet.

Try `/bbt refresh economy` or `/bbt refresh points`, then review the console warning if it fails again. A PlayerPoints failure does not affect the Vault leaderboard, and a Vault failure does not erase the last successful cache.

### A config value is ignored

BetterBaltop validates each setting. Invalid values are replaced with safe defaults, and the console lists the affected paths.

Compare your file with the example on the Configuration page. YAML indentation must use spaces, not tabs.

### I changed a balance but the GUI still shows the old value

The GUI reads a cached snapshot and does not query the economy every time it opens. Run:

```
/bbt refresh economy
```

Wait for the refresh to complete, then reopen the menu or leave it open for the automatic update.


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.cheddah-development.net/plugin-documentaion/better-baltop/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.