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

# troubleshooting

## First diagnostic commands

Run `/skills admin status`, `/skills admin validate`, `/skills level`, and `/skills points`. Inspect `logs/latest.log` for the actual validation/database/network failure. Change one cause at a time; do not delete the database or replace every config to investigate a UI issue.

| Symptom                                        | Check                                                                                                                                    |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Server refuses startup                         | Correct server jar, Java 21, supported Minecraft/NeoForge/Pixelmon APIs, duplicate jars, exact first exception                           |
| Server reports invalid YAML                    | Spaces not tabs, matching indentation, quoted hex/colon strings, one root map, no duplicate IDs                                          |
| `indicator indent must be smaller than indent` | Older serializer/build or invalid output; use current server and validate the file, not random whitespace surgery on all files           |
| Custom UI never opens                          | Compatible engine only, negotiated protocol 20, client permission, no duplicate legacy client                                            |
| Editor unavailable                             | Engine installed; menu/admin/edit permission; server-issued session, correct tree, not expired                                           |
| Publish says stale/session invalid             | Another publish/reload or expired session; reopen and reapply deliberately                                                               |
| Node rank one cannot upgrade                   | `max-rank`, next cost/balance, requirements/conflicts, trial for next rank, selected options still valid                                 |
| Node does not grant expected effect            | Accessible active tree, chosen bundle, rank values, supported gameplay consumer, matching context filters                                |
| Node icon still looks procedural               | Actual `icon` field, valid registry/alias, server validation, theme backplate versus item silhouette                                     |
| Text keys appear literally                     | Missing/old locale, exact consumed key, old engine, translations reloaded and screen reopened                                            |
| Text/labels move differently after publish     | Rendering transform/version mismatch; test both editor/player with same world geometry, do not rewrite coordinates to compensate blindly |
| Quest makes no progress                        | Enabled, right event/filters, accepted branch, prerequisites, class gate, trainer level, already complete/capped                         |
| Quest progresses but XP is unexpected          | Explicit `reward.xp`, old amount×100 migration, source modifiers, max-level floor                                                        |
| XP arrives twice as fast as expected           | Automatic XP plus quest completion plus Journey/node/integration rewards                                                                 |
| No points after raising/lowering levels        | Highest-ever level ledger, currency cap, configured point rewards; old highs do not pay again                                            |
| A rival branch is locked                       | Quest conflict/acceptance, subclass commitment, effect-choice conflict/group, or Journey selection budget—different systems              |
| `/skills` opens inaccessible class/tree        | Correct class `trees`, restrictions/convergence and current builds; explicit tree requests still checked                                 |
| Hero not rerolling                             | Fate is one chance per player/class; normal refresh/reset is not reroll; inspect status                                                  |
| Hero appeared but cannot be selected           | Holder limit rechecked, class max/requirements/permissions, inactivity forfeit                                                           |
| Global Hero audio plays at selection           | Current 5.15.0 trigger discrepancy documented in the Hero guide, not solved by changing its field name                                   |
| Loot bonus never appears                       | Real first loot-table generation, player opener/block entity, right table ID, valid registry item, not an icon alias                     |
| Permission perk has no external effect         | Native API scope versus actual command provider, tested grant/revoke command, installed permission mod                                   |
| Leaderboard is empty                           | Opt-in, included/excluded classes, source progress, enabled boards                                                                       |
| HUD covers menus                               | Keep RPG HUD/studio disabled; distinguish local Journey tracker                                                                          |
| Database startup failure                       | Valid path/URL, driver, credentials, write permissions, backup before migration                                                          |

## Lean staging test checklist

{% stepper %}
{% step %}

### Start with current jars

Validation has no errors.
{% endstep %}

{% step %}

### Verify class and tree access

Ordinary player chooses one permitted class; `/skills` opens a granted tree.
{% endstep %}

{% step %}

### Test quest progress and XP

Start a quest, perform one nonmatching action and matching actions; verify one completion XP award.
{% endstep %}

{% step %}

### Confirm level-point rewards

Confirm level points equal base + periodic + milestone rewards and do not replay.
{% endstep %}

{% step %}

### Test rank purchase limits

Buy a rank with exact points, then attempt another without enough points.
{% endstep %}

{% step %}

### Test selectable-effect nodes

Buy a selectable-effect node; incompatible picks fail; only chosen buffs appear.
{% endstep %}

{% step %}

### Verify node state changes

Upgrade/refund/export/apply that node; choices persist or clear as documented.
{% endstep %}

{% step %}

### Verify rival branch locking

Select one quest/subclass branch and verify the rival is locked.
{% endstep %}

{% step %}

### Test label publishing and positioning

Create/edit/publish a label; compare player positions in Chronicle and Parallax.
{% endstep %}

{% step %}

### Test loot first-open behavior

Test a newly generated loot chest; reopen it and verify no repeated first-open roll.
{% endstep %}

{% step %}

### Test permission grant and refund

Test permission grant/refund with a harmless feature permission, not admin powers.
{% endstep %}

{% step %}

### Test privacy and accessibility settings

Test privacy and a smaller client window with reduced motion enabled.
{% endstep %}
{% endstepper %}

For Hero testing, temporarily use a **staging** Hero with 100% odds and one holder. Grant/selection, capacity, revoke/reroll and a controlled inactivity test can verify behavior without gambling through many accounts. Restore real odds/timeouts before production.

## What to include in a bug report

Server/engine versions, Minecraft/NeoForge/Pixelmon versions, minimal relevant redacted YAML, exact command/action, class/tree/node/quest IDs, error text and the first relevant log exception. For layout issues include window dimensions, GUI scale, theme ID, screenshots of editor/player views, and whether the same published revision is loaded.

{% hint style="danger" %}
Never post database files, private passwords, full personal player data, or every unrelated server config in a public GitBook issue.
{% endhint %}