Wiki Release: 2026.09.5 · UltimateClans: 9.1.4 · Documentation branch: 9 · ClanRaids
ClanRaids troubleshooting#
Use this page when ClanRaids 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 |
|---|---|---|
| Raid definition exists but cannot start | Environment, requirements, participant limits or referenced content is invalid | Check raid validation/admin diagnostics and every referenced mob/boss/reward/environment ID. |
| Lobby never starts countdown | Not all required players are ready or minimum participant requirements are not met | Review lobby.require-all-ready, leader auto-ready, player count and readiness. |
| Wave objective never completes | Spawned entities were not tracked/removed, mob ID is wrong, or entities left the raid boundary | Check active runtime mobs, boundary settings and the exact wave/mob definition. |
| Boss spawns with unexpected entity/health | Boss definition or integration mapping does not match the configured entity | Verify boss type/implementation and startup integration availability; inspect boss-specific debug output. |
| INSTANCE raid cannot create environment | Template/world instance source is absent or instance settings are incomplete | Verify the configured template/environment folder and instance provider settings before starting. |
| Scoreboard/objective appears stuck | Objective event listener is not receiving the required action or stage transition is pending | Check objective type, target values and stage-transition delay; reproduce with debug enabled. |
Configuration validation#
Focus on these configuration areas for this component: general, lobby, session, gameplay, integration, admin, debug. 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#
bosses.ymlchat.ymlcommands.ymlconfig.ymlgui.ymllanguage/Lang_EN.ymlmobs.ymlraids.ymlrewards.yml