Troubleshooting

Complete guide to resolving common plugin issues.

The quest menu does not open

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

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

Solution:

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

Quests appear as locked

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

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

Solution:

1. Verify the template in the BetonQuest package:

   templates:
     - trackedQuest

2. Verify that the activation event exists:

   events:
     activate: "activeQuest my_quest"

3. Test manually by adding the tag:

   /bq tag add <player> my_quest.questTrackable

Quests do not appear in the correct category

Symptom: Quests appear in the wrong category or in the default category.

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

Checks:

1. Compare the values exactly (including case and accents):

   # config.yml
   menuItems:
     categories:
       dailyQuests:
         displayName: "Daily"  # ← This is the value that matters

   # BetonQuest package.yml
   questParameters:
     questCategory: "Daily"  # ← Must be identical

2. If no displayName is defined, the plugin uses the configuration key (e.g., dailyQuests).

3. For subcategories:

   questCategory: "Daily.Monsters"  # Format: displayName.subcategory_displayName

Accents and case

"Daily" is not the same as "daily" or "DAILY". The match must be exact.

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 tracked	The player must track at least one quest
Quest without steps	Define 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 track a quest:

   /quests track <quest_id>

3. Verify 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 synchronize between servers.

Checks:

1. Redis connection: /kgquests redis
2. Same Redis 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 config.yml
Incorrect credentials	Check the BetonQuest MySQL config
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. Verify 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 at startup

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

Solutions:

1. Check the license file:

   plugins/kginfoservs_queststrack/license.key

2. File content: a single line, no leading/trailing spaces

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

   • Outbound firewall
   • Server internet connection
   • Proxy if applicable

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

Degraded performance

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

Diagnostics:

/kgquests stats      # Cache hit rates
/kgquests benchmark  # Detailed latencies
/kgquests memory     # JVM memory
/kgquests health     # Overall health

Indicators:

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

Diagnostic tools

Diagnostic commands

/kgquests health      # Global 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
/kgquests benchmark   # Latency tests (DB, Redis, cache)
/kgquests analytics   # Quest completion statistics

Viewing 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 functional
• MySQL enabled in BetonQuest (mysql.enabled: true)
• Database accessible (/kgquests health)
• Valid configuration (/questsreload without errors)
• trackedQuest template on quests
• questCategory matches the displayName (case and accents)
• BetonQuest events configured (activeQuest, etc.)
• quests_config.yml filled in (title, steps)
• Server logs checked for errors

Getting help

If the issue persists:

1. Gather information:

   • Minecraft, Paper, 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 -- Configuration key reference
• BetonQuest Integration -- Events and templates
• Multi-server -- Redis configuration
• Installation -- Installation guide