Wiki Release: 2026.09.5 · UltimateClans: 9.1.4 · Documentation branch: 9 · ClanQuest

ClanQuest troubleshooting#

Use this page when ClanQuest 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
Quest progress stays at zero	Objective type/target does not match the event being generated, world/region/permission filters block it, or the quest is not active	Confirm active quest and objective type, then reproduce one exact matching action with debug/logging enabled.
Quest completes but reward is missing	Reward/action configuration failed or external economy/command integration is unavailable	Inspect finish event/reward configuration and console output; test reward command manually.
Changing a quest ID loses progress	Persistent player data references the original ID	Do not rename live quest IDs without migration/backups.
Integration objective never advances	Required plugin/integration listener is unavailable	Confirm the dependency is installed and detected at startup, then test its native event first.

Configuration validation#

Focus on these configuration areas for this component: Config, Storage. Preserve exact YAML indentation and key names.

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.

Files worth checking#

commands.yml
config.yml
gui.yml
language/Lang_EN.yml
polymart.yml
quests.yml