Wiki Release: 2026.09.5 · UltimateClans: 9.1.4 · Documentation branch: 9 · Mail
Mail troubleshooting#
Use this page when Mail 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 |
|---|---|---|
| Mail sends but recipient clan cannot see it | Target resolution/storage save failed or mailbox filter hides it | Check target clan and persisted mail record. |
| Unread count stays wrong | Read-state update/cache did not persist | Reopen mailbox and inspect storage errors. |
| Mail disappears early | Expiry/cleanup setting is too short | Review retention/expiry configuration. |
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.ymlconfig.ymlgui.ymllanguage/Lang_EN.ymllanguage/Lang_ES.yml