Troubleshooting
Solutions for common issues with the Achievement & Title System.
Installation Issues
Section titled “Installation Issues”Plugin Not Loading
Section titled “Plugin Not Loading”Symptoms:
- No log messages from plugin
- Commands not working
Solutions:
-
Check Java version (requires Java 25):
Terminal window java -version -
Verify JAR is in correct folder:
mods/KyuubiSoftAchievements-3.1.6.jar ✓mods/kyuubisoft_achievements/KyuubiSoftAchievements-3.1.6.jar ✗ -
Make sure KyuubiSoft Core is installed (required; 3.1.6 needs Core 2.9.9 or newer)
-
Check for startup errors in server log
-
Ensure compatible Hytale server version (0.7.x)
Missing Configuration Files
Section titled “Missing Configuration Files”Symptoms:
- Config files not generated
- Errors about missing files
Solutions:
- Ensure plugin loaded successfully
- Check write permissions on the
mods/folder - Restart server (not just reload)
- Check for disk space issues
Achievement Issues
Section titled “Achievement Issues”Achievements Not Unlocking
Section titled “Achievements Not Unlocking”Symptoms:
- Progress updates but achievement doesn’t unlock
- No notification when meeting requirements
Solutions:
-
Check prerequisites:
Terminal window /acadmin list YourNameVerify all required achievements are unlocked. The detail panel of the book shows the requirements with met markers.
-
Is the achievement disabled or “Special”? Disabled achievements (admin window) are not counted. Achievements with the
manualtrigger only unlock by an admin grant. -
MMO skill levels: only the milestones 10 / 25 / 50 / 75 / 100 and the total milestones are sent; other
skill_leveltargets never unlock. The check view of the admin window lists such problems. -
Check trigger type matches action:
blocks_mined= Breaking blocks (not placing)kills= Dealing final blow (not assists)
-
Check target matching:
- Exact match:
"Spider"only matches Spider "any"matches everything- Prefix match:
"Ore_"matches Ore_Iron, Ore_Gold, etc. - Wildcards:
"Snake_*"matches every snake
- Exact match:
-
Verify count threshold:
"trigger": {"type": "kills","target": "Spider","count": 50 ← Must reach exactly 50+}
Progress Not Tracking
Section titled “Progress Not Tracking”Symptoms:
- Progress stays at 0
- Actions not being counted
Solutions:
-
Check tracking is enabled:
"tracking": {"enableCombat": true, ← Check these"enableProgression": true} -
Verify correct trigger type:
- Mining stone? Use
blocks_mined - Crafting sword? Use
items_crafted
- Mining stone? Use
-
Check server logs for errors: Look for tracking-related exceptions
Hidden Achievement Stuck
Section titled “Hidden Achievement Stuck”Symptoms:
- Hidden achievement shows ”???” even after unlocking
Solutions:
- Refresh UI (close and reopen
/ksachievements) - Check achievement is actually unlocked:
Terminal window /acadmin list YourName - Verify
hidden: trueis set in achievement definition
Title Issues
Section titled “Title Issues”Title Not Showing on Nametag
Section titled “Title Not Showing on Nametag”Symptoms:
- Title selected but not visible
- Nametag shows only username
Solutions:
-
Check display mode:
"display": {"displayMode": "both" ← Should include "nametag" or "both"} -
Verify title is selected:
- Open
/kstitles - Check the active title at the top of the Titles tab
- Open
-
Check title position:
"display": {"titlePosition": "prefix" ← Try different positions} -
KyuubiSoft Nameplates installed? Then the title is shown as a nameplate tag of that mod, not in the nameplate text.
-
Restart/rejoin: Title updates may require reconnecting
Title Not in the Titles Tab
Section titled “Title Not in the Titles Tab”Symptoms:
- Achievement unlocked but title not available
Solutions:
-
Verify achievement has title:
"title": {"id": "my_title","color": "#FFD700"} -
Check title ID has translation:
achievements.title.my_title=My Title Name
LuckPerms Issues
Section titled “LuckPerms Issues”Prefix Not Showing
Section titled “Prefix Not Showing”Symptoms:
- LuckPerms prefix not appearing in chat
- Only achievement title shows
Solutions:
-
Verify LuckPerms is installed:
Terminal window /lp info -
Check prefix is set:
Terminal window /lp user YourName info -
Verify prefix syntax:
Terminal window # Correct/lp group admin meta setprefix 100 "<red>[Admin]</red> "# Wrong (missing space at end)/lp group admin meta setprefix 100 "<red>[Admin]</red>" -
Check server logs for:
[KyuubiSoft Achievements] LuckPerms integration enabled
Colors Not Working
Section titled “Colors Not Working”Symptoms:
- Prefix shows but without colors
- Raw tags visible:
<red>[Admin]</red>
Solutions:
-
Use correct MiniMessage syntax:
<red>Text</red> ✓&cText ✓ (legacy)<#FF5555>Hex</end> ✗ (wrong close tag)<#FF5555>Hex</#FF5555> ✓ -
Check for unclosed tags:
<bold><red>Text</red> ✗ (missing </bold>)<bold><red>Text</red></bold> ✓
HUD/Toast Issues
Section titled “HUD/Toast Issues”Toast Not Appearing
Section titled “Toast Not Appearing”Symptoms:
- Achievement unlocks but no banner
- Only chat message shows
Solutions:
-
Check notification settings:
"notifications": {"enabled": true,"displayMode": "banner" ← or "both"} -
The world map is open: the HUD and toast hide while the map is open.
-
HUD conflicts are no longer an issue: since 3.0.0 every mod has its own HUD slot. If another mod or a window removed custom HUDs, the tracker is put back automatically. No extra HUD mod is needed.
-
Toast shows lower than usual: since 3.1.6 the toast appears right below the compass and shares those rows with the toasts of the other KyuubiSoft mods. It takes the highest free row and moves lower only while another toast is still on screen. This needs KyuubiSoft Core 2.9.9 or newer.
Performance Issues
Section titled “Performance Issues”Server Lag
Section titled “Server Lag”Symptoms:
- Lag spikes when achievements unlock
- Slow UI loading
Solutions:
-
Increase save interval:
"tracking": {"saveIntervalSeconds": 600 ← Increase from 300} -
Disable unused tracking:
"tracking": {"enableExploration": false ← If not needed} -
Reduce export frequency:
"export": {"intervalSeconds": 600}
High Memory Usage
Section titled “High Memory Usage”Symptoms:
- Memory increases over time
- OutOfMemoryError
Solutions:
-
Check player data accumulation:
- Large number of unique players = more memory
- Consider archiving old player data
-
Reduce leaderboard size:
"export": {"leaderboardSize": 50 ← Reduce from 100}
Data Issues
Section titled “Data Issues”Lost Progress
Section titled “Lost Progress”Symptoms:
- Achievement progress reset
- Unlocked achievements missing
Solutions:
-
Check for save errors in logs
-
Verify data file exists:
mods/kyuubisoft_achievements/players/<uuid>.jsonA broken player file is kept as
<uuid>.json.corrupt-<time>and the.bakcopy is loaded instead of empty data. -
Check disk space
-
Content lost after a save in the admin window? Use Undo last save in the General settings page; every save keeps a backup set (last 20).
Duplicate Achievements
Section titled “Duplicate Achievements”Symptoms:
- Same achievement shows multiple times
- Warnings in server log
Solutions:
-
Check for duplicate IDs: the check view of the admin window lists them with Go to.
-
Regenerate the standard file: delete
configs/achievements.jsonand restart; your entries incustom/stay.
Getting Help
Section titled “Getting Help”If none of the above solutions work:
-
Check server logs for detailed error messages
-
Enable debug logging: Set Java logging level to FINE for detailed output
-
Gather information:
- Server version
- Plugin version
- Relevant config sections
- Error messages from logs
-
Report issue: Create an issue with all gathered information