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

ClanGuardian troubleshooting#

Use this page when ClanGuardian 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
Guardian does not spawn	Default/selected type unavailable, entity implementation failed to initialize, world/context is invalid or profile is defeated	Check `guardians.yml`, selected type, startup EntityWizard/entity integration logs and `/clan guardian info`.
Guardian follows but never attacks	PASSIVE/STAY/support behavior, target filtering, leash/radius or clan relationship rules prevent targeting	Switch to an attacking mode for the test, move a valid hostile target inside `combat.target-radius`, then inspect debug target/skill output.
Guardian teleports or moves awkwardly	Follow distance, forward offset, speed or teleport distance are too aggressive for the entity type	Return follow settings near defaults and tune one value at a time.
Skill never activates	Skill is not equipped, trigger/condition fails, cooldown/energy requirement is not met, or target is invalid	Enable `debug.skill-failures`, reproduce once and use the reported condition rather than lowering all limits blindly.
HUD shows wrong/stale values	HUD mode or update timing differs from the active guardian state	Check `hud.enabled`, mode/only-in-combat and reopen/respawn the guardian after config changes.
Shared clan guardian is absent	Feature disabled, clan level too low, max reached or no eligible online member can be followed	Check `shared-guardian.*`, clan level and online-member requirements.

Configuration validation#

Focus on these configuration areas for this component: general, follow, combat, debug, hud, indicator, settings, shared-guardian. 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
guardians.yml
gui.yml
languages/Lang_EN.yml
skills/basic_attack.yml
skills/clan_regeneration_aura.yml
skills/heal.yml
skills/item_collector.yml
skills/last_stand.yml
skills/power_strike.yml
skills/ranged_attack.yml