Troubleshooting

Complete guide to resolving common issues with the plugin.

The quest menu does not open

Symptom: The /quests command does nothing or shows an error.

Cause	Check	Solution
Plugin not loaded	/plugins in-game	Check the loading errors in the logs
BetonQuest missing	/plugins in-game	Install BetonQuest 3.0+
Database unreachable	/kgquests health	Check that BetonQuest has MySQL enabled
License error	Server logs	Check the license.key file

Solution:

1. Check that the plugin is loaded (green in /plugins)
2. Check the startup logs for errors
3. Check the database connection: /kgquests health

Quests appear as locked

Symptom: The menu opens but all quests have a "Locked" status.

Cause	Solution
trackedQuest template missing	Add templates: [trackedQuest] in the BQ package
activeQuest event not triggered	Check that the event is properly called in the BQ logic
.questTrackable tag missing	Test manually: /bq tag add <player> ma_quete.questTrackable

Solution:

1. Check the template in the BetonQuest package:

   templates:
     - trackedQuest

2. Check that the activation event exists:

   events:
     activer: "activeQuest ma_quete"

3. Test manually by adding the tag:

   /bq tag add <player> ma_quete.questTrackable

Quests do not appear in the right category

Symptom: Quests appear in the wrong category or in the default category (other).

Main cause: The questCategory in BetonQuest does not match the configKey of the category in config.yml.

Checks:

1. Compare the values exactly (the value is case-sensitive):

   # config.yml
   menuItems:
     categories:
       dailyQuests:        # ← This is the key (configKey) that matters
         displayName: "Daily"

   # BetonQuest package.yml
   questParameters:
     questCategory: dailyQuests  # ← Must match the YAML key exactly

2. For subcategories, combine the parent and child configKey with a dot:

   questCategory: dailyQuests.monsters  # Format: configKey.subConfigKey

3. If no questCategory is defined, the quest falls into the category defined by defaultCategory in config.yml.

Migration from an older version

Before a recent update, questCategory used the displayName (e.g. "Story"). Now it requires the configKey (e.g. story). If all your quests have suddenly moved into the other category, this is probably the cause.

Update your BetonQuest package.yml files:

• questCategory: "Story" → questCategory: story
• questCategory: "Daily" → questCategory: dailyQuests
• questCategory: "Daily.Monsters" → questCategory: dailyQuests.monsters

The scoreboard or menu stays in the old language after /questlang

Symptom: A player runs /questlang fr-FR (or /ql en-US) but the scoreboard / quest journal does not immediately switch language.

Cause: You are using an older version of the plugin that does not detect the language change.

Solution:

1. Update the plugin to the latest version
2. After the update, the plugin automatically intercepts /questlang and /ql:
   • The scoreboard is rebuilt in the new language
   • The open quest menu (if any) is refreshed
3. No additional command is needed

Quick test

1. Set up your quests as multilingual (fr-FR + en-US) in quests_config.yml
2. Connect, run /questlang en-US
3. The scoreboard should switch to English immediately
4. Run /questlang fr-FR again to go back to French

The scoreboard does not display

Symptom: Tracked quests do not show a scoreboard.

Cause	Solution
Scoreboard disabled globally	Check scoreboard.enabled: true in config.yml
No quest being tracked	The player must be tracking at least one quest
Quest with no steps	Define the steps in quests_config.yml
Conflict with another plugin	Check for conflicts with TAB, Featherboard, etc.

Solution:

1. Check the global scoreboard configuration:

   scoreboard:
     enabled: true

2. The player must be tracking a quest:

   /quests track <quest_id>

3. Check that the quest has steps in quests_config.yml

4. Test the scoreboard:

   /kgquests scoreboard on

The cache does not update

Symptom: Quest changes are not reflected immediately.

Solutions:

1. Force a refresh for a player:

   /kgquests refresh <player>

2. Reload the configuration:

   /questsreload

3. Check the hit rates:

   /kgquests stats

Cache TTL

The local cache (L1) expires after 1-2 minutes, the Redis cache (L2) after 2 minutes. If you need an immediate refresh, use /kgquests refresh.

Multi-server issues (Redis)

Symptom: Data does not sync between servers.

Checks:

1. Redis connection: /kgquests redis
2. Same Redis instance for all servers (check host:port in each config.yml)
3. Same BetonQuest database for all servers
4. Firewall: Redis port (6379) open between servers
5. Force a refresh: /kgquests refresh <player>

See Multi-server for the detailed guide.

Database errors

Symptom: SQLException or HikariPool errors in the logs.

Cause	Solution
MySQL disabled in BQ	Enable mysql.enabled: true in BetonQuest's config.yml
Incorrect credentials	Check BetonQuest's MySQL configuration
MySQL server stopped	Restart MySQL/MariaDB
Connection pool exhausted	Restart the plugin
Network timeout	Check the connection between the MC server and the database

Solution:

1. Check the connection: /kgquests health
2. Check that BetonQuest has MySQL enabled:

   # plugins/BetonQuest/config.yml
   mysql:
     enabled: true

3. Test the connection manually:

   mysql -h localhost -u betonquest -p betonquest

License error on startup

Symptom: The plugin does not load and shows a license error.

Solutions:

1. Check the license file:

   plugins/KGInfoServs-QuestsTrack/license.key

2. File content: a single line, no spaces before/after

3. Internet access: the server must be able to reach the license server. Check:

   • Outbound firewall
   • The server's Internet connection
   • Proxy, if applicable

4. Contact support: if the problem persists, contact KGInfoServs on Discord

Degraded performance

Symptom: The menu is slow to open, the scoreboard lags.

Diagnostics:

/kgquests stats      # Cache hit rate
/kgquests memory     # JVM memory
/kgquests health     # Overall health

Indicators:

Indicator	Issue	Solution
Cache hit < 85%	Inefficient cache	Check the number of players vs cache size
Database latency > 50ms	Slow database	Optimize MySQL, move the database closer to the MC server
Redis latency > 10ms	Remote Redis	Put Redis on the same network
Memory > 80%	Insufficient memory	Increase the JVM heap (-Xmx)

Diagnostic tools

Diagnostic commands

/kgquests health      # Overall check of all components
/kgquests stats       # Cache statistics (hit rate, misses)
/kgquests redis       # Redis connection status
/kgquests redis <p>   # A specific player's Redis cache
/kgquests memory      # JVM memory and caches

View logs in real time

Linux:

tail -f logs/latest.log | grep -i queststrack

Windows (PowerShell):

Get-Content logs/latest.log -Wait | Select-String -Pattern "queststrack"

Quick troubleshooting checklist

Before asking for help, check:

• Plugin loaded (green in /plugins)
• BetonQuest installed and working
• MySQL enabled in BetonQuest (mysql.enabled: true)
• Database reachable (/kgquests health)
• Valid configuration (/questsreload with no error)
• trackedQuest template on the quests
• questCategory matches the configKey (YAML key) of a category in config.yml
• BetonQuest events configured (activeQuest, etc.)
• quests_config.yml filled in (title, steps)
• Server logs checked for errors

Getting help

If the problem persists:

1. Gather the information:

   • Minecraft, Paper, and Java versions
   • BetonQuest and QuestsTracker versions
   • Output of /kgquests health
   • Server logs (lines with errors)
   • Your config.yml (without passwords)

2. Contact support:

   • KGInfoServs Discord: https://discord.gg/SZhD9AGUXW

See also

• Configuration — Reference for configuration keys
• BetonQuest integration — Events and templates
• Multi-server — Redis configuration
• Installation — Installation guide