FiveM « server thread hitch warning » : ce que ça signifie et comment corriger

Un avertissement comme « server thread hitch warning: timer interval of 250 milliseconds » signifie que la boucle principale du serveur s'est bloquée pendant cette durée. Les joueurs le ressentent comme du rubber-banding, des actions retardées et de la désynchronisation. Voici comment trouver la cause au lieu de deviner.

Par l'équipe Nodewave · Mis à jour le 8 novembre 2026

Ce que signifie l'avertissement

FXServer exécute l'essentiel de la logique du jeu, y compris chaque script serveur, sur un seul thread principal. Chaque passage de cette boucle devrait prendre quelques millisecondes. Quand l'un d'eux dure bien plus, la console affiche un avertissement de hitch avec la durée du blocage. Des avertissements similaires peuvent citer le thread réseau ou de synchronisation.

• Quelques hitches au démarrage du serveur sont normaux : les ressources se chargent et la base de données se met en route.
• Des hitches qui se répètent pendant le jeu signalent un problème, et les joueurs le remarqueront.

1. Trouvez la ressource avec le profiler

FXServer intègre un profiler. Lancez-le dans la console du serveur (la Live Console de txAdmin), pas dans la console F8, pendant que les hitches se produisent :

profiler record 500
profiler status
profiler saveJSON hitch.json

profiler record 500 capture les 500 prochaines frames. Quand profiler status indique que la capture est terminée, enregistrez-la, ouvrez les outils de développement de Chrome, allez dans l'onglet Performance et chargez le fichier. Les hitches apparaissent comme de hauts pics ; zoomez sur l'un d'eux pour voir quelle ressource a pris le temps, jusqu'au fichier et à la ligne.

2. Corrigez les causes habituelles dans les scripts

• Les boucles qui tournent à chaque tick. Une boucle serveur avec Wait(0) tourne aussi souvent que possible. La plupart des boucles serveur peuvent attendre des centaines ou des milliers de millisecondes entre deux passages.
• Traiter chaque joueur ou entité d'un coup. Parcourir tous les joueurs ou véhicules chaque seconde devient coûteux à mesure que la ville grandit. Étalez le travail, ou réagissez à des événements au lieu de vérifier en permanence.
• Des requêtes de base de données lentes. Une requête qui parcourt une grosse table sans index peut prendre des centaines de millisecondes. oxmysql signale les requêtes lentes dans la console ; ajoutez des index sur les colonnes qu'elles recherchent, et n'exécutez pas de requêtes dans des boucles serrées.
• Le spam d'événements. Des clients qui déclenchent des événements serveur plusieurs fois par seconde, par erreur ou par triche, occupent le thread principal. Limitez la fréquence des événements coûteux.
• Les anciennes ressources. Supprimez les scripts que vous n'utilisez plus, et mettez à jour ceux que vous gardez.

3. Vérifiez le serveur de base de données

Les serveurs de roleplay écrivent en permanence dans la base de données. Gardez MariaDB sur la même machine ou très près, sur du stockage NVMe, avec assez de mémoire. Purgez les tables de logs qui grossissent sans limite, et sauvegardez la base régulièrement.

4. Vérifiez l'hébergement

• Vitesse du CPU. Le thread principal utilise un seul cœur : la vitesse mono-thread décide donc de la quantité de travail des scripts qui tient dans chaque frame. Un cœur lent ou surchargé chez l'hébergeur transforme de petits coûts de scripts en hitches.
• L'antivirus sur les serveurs Windows. L'analyse en temps réel d'un gros dossier serveur peut consommer beaucoup de CPU. Sur des serveurs Windows que nous accompagnons, Microsoft Defender a utilisé plus de CPU que FXServer lui-même. Excluez de l'analyse le dossier du serveur, FXServer.exe et le programme de base de données, et gardez la protection en temps réel pour tout le reste.
• Les autres programmes sur la même machine. Les bots, panneaux web et sauvegardes qui tournent aux heures de pointe se disputent le même CPU.

Du lag sur l'écran de certains joueurs seulement ?

Le lag côté client est différent d'un hitch serveur. Si seuls certains joueurs saccadent, demandez-leur d'ouvrir la console F8 et de lancer resmon 1 pour voir quelles ressources prennent le plus de temps de leur côté.

Éviter que ça revienne

• Profilez après l'ajout de tout gros script, pas des semaines plus tard.
• Surveillez le graphique CPU de votre serveur aux heures de pointe.
• Testez les mises à jour d'abord sur une copie du serveur.

Les erreurs de script dans la console, comme « attempt to index a nil value », sont un autre problème. Voyez comment corriger cette erreur dans les scripts ESX et QBCore.