Wiki Release: 2026.09.5 · UltimateClans: 9.1.4 · Documentation branch: 9 · ClanChest
ClanChest troubleshooting#
Use this page when ClanChest loads but a gameplay/admin workflow does not behave as expected. Start with the narrow symptom rather than changing multiple configuration sections at once.
Fast diagnostic order#
- Confirm the component loaded and its required Core version is compatible.
- Reproduce with a non-OP test account and verify the exact command/role permission.
- Check YAML syntax and the specific feature section involved.
- Verify optional providers (economy, map, hologram, entity, Redis, WorldGuard, etc.) only when that feature depends on them.
- Check persistent storage and cross-server synchronization after configuration/permission checks.
- Read the first component-specific console error produced during startup or reproduction.
Common symptoms#
| Symptom | Likely causes | What to check / fix |
|---|---|---|
| A member can open a page but cannot remove items | The page is DEPOSIT_ONLY/LOCKED or the role does not meet the configured access rule | Check the page mode and role requirement; test with leader versus ordinary member. |
| Items appear missing after changing GUI layout | Stored item positions and GUI cosmetic layout were changed inconsistently | Restore the page/storage layout from backup and change only documented cosmetic slots. |
| Two servers show different chest state | Nodes use different storage, page configuration or synchronization state | Verify identical addon config, shared database where intended, and check locking/sync errors on both nodes. |
| Page purchase/unlock does nothing | Economy/unlock requirements or clan permissions are not satisfied | Check economy provider, price/unlocker settings and the member role permission. |
Configuration validation#
This component has little/no installed configuration in the supplied snapshot; use its source defaults and command feedback as the primary validation source.
Storage and restart checks#
- Do not delete live storage as a first troubleshooting step. Make a backup and inspect it first.
- If the issue appears only after restart, compare what is persisted with what is rebuilt in memory at startup.
- If the issue appears only on one server in a network, compare the component version, config, database and sync channel on that server.
- After a failed migration/recovery operation, keep the original data until the failure is understood.
What to include in a support ticket#
Provide the product/core version, component version, Minecraft/server implementation, the exact command/action used, the relevant config section, and the first related console error. Avoid sending passwords, database credentials, webhook secrets or API keys.
Diagnostic workflow#
Use this order before changing multiple settings at once:
- Startup: find the first warning/error mentioning this component; later exceptions are often consequences.
- Version/dependencies: verify the parent plugin version and every required/optional integration actually detected at startup.
- Configuration: validate YAML indentation/types and compare the relevant path with the default documented in this Wiki.
- Access: test both Bukkit permission and UltimateClans role/internal permission using a non-OP player.
- Context: reproduce in an allowed world/region and check claim/PvP/economy hooks if the feature depends on them.
- Persistence: restart and verify state is loaded from the intended YAML/SQLite/MySQL backend.
- Multiserver: reproduce on a single node first, then verify identical configs/storage/sync on all nodes.
- Isolation: disable unrelated integrations one at a time only when the evidence points to a hook conflict.
What to include when requesting support#
- Exact plugin/core/component versions.
- The command/action performed and expected result.
- The first relevant console exception/warning, not only the last line.
- The relevant configuration section with secrets removed.
- Whether the problem reproduces with a non-OP player.
- Server software/version and whether the server is part of a multiserver network.