Depannage

Guide complet pour resoudre les problemes courants du plugin.

Le menu de quetes ne s'ouvre pas

Symptome : La commande /quests ne fait rien ou affiche une erreur.

Cause	Verification	Solution
Plugin non charge	/plugins en jeu	Verifiez les erreurs de chargement dans les logs
BetonQuest manquant	/plugins en jeu	Installez BetonQuest 3.0+
BDD inaccessible	/kgquests health	Verifiez que BetonQuest a MySQL active
Erreur de licence	Logs serveur	Verifiez le fichier license.key

Solution :

1. Verifiez que le plugin est charge (vert dans /plugins)
2. Consultez les logs au demarrage pour les erreurs
3. Verifiez la connexion BDD : /kgquests health

Les quetes apparaissent comme verrouillee

Symptome : Le menu s'ouvre mais toutes les quetes ont le statut "Bloque".

Cause	Solution
Template trackedQuest absent	Ajoutez templates: [trackedQuest] dans le package BQ
Event activeQuest non declenche	Verifiez que l'event est bien appele dans la logique BQ
Tag .questTrackable manquant	Testez manuellement : /bq tag add <joueur> ma_quete.questTrackable

Solution :

1. Verifiez le template dans le package BetonQuest :

   templates:
     - trackedQuest

2. Verifiez que l'event d'activation existe :

   events:
     activer: "activeQuest ma_quete"

3. Testez manuellement en ajoutant le tag :

   /bq tag add <joueur> ma_quete.questTrackable

Les quetes n'apparaissent pas dans la bonne categorie

Symptome : Les quetes apparaissent dans la mauvaise categorie ou dans la categorie par defaut.

Cause principale : Le questCategory dans BetonQuest ne correspond pas au displayName de la categorie dans config.yml.

Verifications :

1. Comparez les valeurs exactement (casse et accents compris) :

   # config.yml
   menuItems:
     categories:
       dailyQuests:
         displayName: "Daily"  # ← C'est cette valeur qui compte

   # BetonQuest package.yml
   questParameters:
     questCategory: "Daily"  # ← Doit etre identique

2. Si aucun displayName n'est defini, le plugin utilise la cle de configuration (ex: dailyQuests).

3. Pour les sous-categories :

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

Accents et casse

"Journaliere" ≠ "Journalière" ≠ "journaliere". La correspondance est exacte.

Le scoreboard ne s'affiche pas

Symptome : Les quetes suivies ne montrent pas de scoreboard.

Cause	Solution
Scoreboard desactive globalement	Verifiez scoreboard.enabled: true dans config.yml
Aucune quete suivie	Le joueur doit suivre au moins une quete
Quete sans etapes	Definissez les steps dans quests_config.yml
Conflit avec un autre plugin	Verifiez les conflits avec TAB, Featherboard, etc.

Solution :

1. Verifiez la configuration globale du scoreboard :

   scoreboard:
     enabled: true

2. Le joueur doit suivre une quete :

   /quests track <quest_id>

3. Verifiez que la quete a des etapes dans quests_config.yml

4. Testez le scoreboard :

   /kgquests scoreboard on

Le cache ne se met pas a jour

Symptome : Les changements de quete ne se refletent pas immediatement.

Solutions :

1. Forcez un refresh pour un joueur :

   /kgquests refresh <joueur>

2. Rechargez la configuration :

   /questsreload

3. Verifiez les taux de hit :

   /kgquests stats

TTL du cache

Le cache local (L1) expire apres 1-2 minutes, le cache Redis (L2) apres 2 minutes. Si vous avez besoin d'un refresh immediat, utilisez /kgquests refresh.

Problemes multi-serveur (Redis)

Symptome : Les donnees ne se synchronisent pas entre serveurs.

Verifications :

1. Connexion Redis : /kgquests redis
2. Meme Redis pour tous les serveurs (verifiez host:port dans chaque config.yml)
3. Meme base de donnees BetonQuest pour tous les serveurs
4. Firewall : port Redis (6379) ouvert entre les serveurs
5. Forcez un refresh : /kgquests refresh <joueur>

Voir Multi-serveur pour le guide detaille.

Erreurs de base de donnees

Symptome : Erreurs SQLException ou HikariPool dans les logs.

Cause	Solution
MySQL desactive dans BQ	Activez mysql.enabled: true dans BetonQuest config.yml
Identifiants incorrects	Verifiez la config MySQL de BetonQuest
Serveur MySQL arrete	Redemarrez MySQL/MariaDB
Pool de connexions epuise	Redemarrez le plugin
Timeout reseau	Verifiez la connexion entre le serveur MC et la BDD

Solution :

1. Verifiez la connexion : /kgquests health
2. Verifiez que BetonQuest a MySQL active :

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

3. Testez la connexion manuellement :

   mysql -h localhost -u betonquest -p betonquest

Erreur de licence au demarrage

Symptome : Le plugin ne se charge pas et affiche une erreur de licence.

Solutions :

1. Verifiez le fichier de licence :

   plugins/kginfoservs_queststrack/license.key

2. Contenu du fichier : une seule ligne, pas d'espaces avant/apres

3. Acces Internet : le serveur doit pouvoir contacter le serveur de licences. Verifiez :

   • Firewall sortant
   • Connexion Internet du serveur
   • Proxy si applicable

4. Contact support : si le probleme persiste, contactez KGInfoServs sur Discord

Performance degradee

Symptome : Le menu est lent a ouvrir, le scoreboard rame.

Diagnostics :

/kgquests stats      # Taux de hit du cache
/kgquests benchmark  # Latences detaillees
/kgquests memory     # Memoire JVM
/kgquests health     # Sante globale

Indicateurs :

Indicateur	Probleme	Solution
Cache hit < 85%	Cache inefficace	Verifiez le nombre de joueurs vs taille du cache
Latence BDD > 50ms	BDD lente	Optimisez MySQL, rapprochez la BDD du serveur MC
Latence Redis > 10ms	Redis distant	Placez Redis sur le meme reseau
Memoire > 80%	Memoire insuffisante	Augmentez le heap JVM (-Xmx)

Outils de diagnostic

Commandes de diagnostic

/kgquests health      # Verification globale de tous les composants
/kgquests stats       # Statistiques du cache (taux de hit, miss)
/kgquests redis       # Etat de la connexion Redis
/kgquests redis <j>   # Cache Redis d'un joueur specifique
/kgquests memory      # Memoire JVM et caches
/kgquests benchmark   # Tests de latence (BDD, Redis, cache)
/kgquests analytics   # Statistiques de completion des quetes

Voir les logs en temps reel

Linux :

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

Windows (PowerShell) :

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

Checklist de depannage rapide

Avant de demander de l'aide, verifiez :

• Plugin charge (vert dans /plugins)
• BetonQuest installe et fonctionnel
• MySQL active dans BetonQuest (mysql.enabled: true)
• BDD accessible (/kgquests health)
• Configuration valide (/questsreload sans erreur)
• Template trackedQuest sur les quetes
• questCategory correspond au displayName (casse et accents)
• Events BetonQuest configures (activeQuest, etc.)
• quests_config.yml rempli (title, steps)
• Logs serveur consultes pour erreurs

Demander de l'aide

Si le probleme persiste :

1. Rassemblez les informations :

   • Version de Minecraft, Paper, Java
   • Version de BetonQuest et QuestsTracker
   • Resultat de /kgquests health
   • Logs serveur (lignes avec erreurs)
   • Votre config.yml (sans les mots de passe)

2. Contactez le support :

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

Voir aussi

• Configuration — Reference des cles de configuration
• Integration BetonQuest — Events et templates
• Multi-serveur — Configuration Redis
• Installation — Guide d'installation