Dépannage

Le message « server thread hitch warning: timer interval of … milliseconds » signifie que le thread principal de FXServer, qui exécute tous les scripts serveur et doit repasser toutes les 50 ms, est resté bloqué plus de 150 ms. La cause la plus fréquente est une ressource qui fait trop de travail d’un coup : boucle Lua, gros traitement de données, rafale de requêtes SQL. Pour la trouver, lancez le profiler du serveur (profiler record) au moment où l’avertissement apparaît, puis ouvrez la capture.

Mise à jour : 15 novembre 2026

Ce que dit le message

L’avertissement s’affiche dans la console du serveur et dans celle de txAdmin, en trois variantes selon le thread (nombres donnés en exemple) :

server thread hitch warning: timer interval of 213 milliseconds
network thread hitch warning: timer interval of 187 milliseconds
sync thread hitch warning: timer interval of 142 milliseconds

Chaque thread de FXServer tourne à intervalle fixe et mesure le temps écoulé depuis son passage précédent. Au-delà d’un seuil, il écrit l’avertissement. Le nombre affiché est cet intervalle complet : le message ne nomme jamais la ressource coupable.

server thread (svMain)
Le thread principal. Il exécute tous les scripts serveur, en Lua, JavaScript ou C#, 20 fois par seconde : un passage toutes les 50 ms. Avertissement au-delà de 150 ms.
network thread (svNetwork)
Il envoie et reçoit les paquets des joueurs, 100 fois par seconde. Avertissement au-delà de 150 ms.
sync thread (svSync)
Il synchronise les entités sous OneSync. Avertissement au-delà de 100 ms.

Un avertissement isolé pendant le chargement des ressources n’a rien d’inquiétant. Il devient un problème quand il revient avec des joueurs connectés : véhicules qui sautent, actions en retard, déconnexions par timeout. Après 45 secondes sans un seul passage, FXServer écrit un message qui contient « seems hung » : le serveur est figé.

Les causes, de la plus fréquente à la plus rare

Tous les scripts serveur partagent le thread principal : une seule ressource qui le monopolise ralentit toutes les autres.

Une boucle Lua trop lourde
Un CreateThread qui parcourt tous les joueurs ou toute une table à chaque tour, un json.encode sur une énorme table, une boucle dont une branche saute le Wait et ne rend plus la main.
Les allocations en rafale
Une fonction qui reconstruit une grosse table à chaque appel, comme la liste des joueurs du framework, appelée des centaines de fois par seconde. Le ramasse-miettes de Lua doit ensuite vider la mémoire, parfois en une longue pause.
La base de données
oxmysql attend les réponses sans bloquer le thread, mais les résultats sont traités dessus. Des milliers de requêtes dans la même seconde, ou des dizaines de milliers de lignes converties en tables Lua, suffisent. Les requêtes lentes, souvent faute d’index, retardent en plus tout ce qui attend leur réponse.
Les tâches périodiques
Sauvegarde de tous les joueurs d’un coup, salaire versé à toute la ville, purge de table. Un avertissement qui revient à intervalle régulier pointe vers elles.
La machine
VPS au processeur partagé, processeur lent en mono-cœur, sauvegarde qui tourne à côté, mémoire qui déborde sur le disque. Les trois variantes apparaissent alors souvent ensemble, même avec peu de joueurs.
Le trafic réseau
Une attaque, ou un script qui inonde le réseau d’événements, charge d’abord les threads réseau et de synchronisation. Une variante « network » ou « sync » seule oriente vers cette piste.

Ce qu’on a vu en production sur un grand serveur RP français : la liste des joueurs du framework, appelée dans des boucles fréquentes, allouait jusqu’à 550 Ko par appel, et les pauses du ramasse-miettes figeaient le serveur de 100 à 650 ms. Une copie de la liste rafraîchie chaque seconde a réglé le problème.

Trouver la ressource coupable

  • Notez quand l’avertissement apparaît : heure, nombre de joueurs, intervalle régulier ou non. Le tableau de bord de txAdmin montre les temps de tick de chaque thread, utile pour voir si le problème suit l’affluence.
  • Enregistrez une capture avec le profiler du serveur, depuis la console de txAdmin. Elle doit contenir un blocage : lancez-la avant, arrêtez-la juste après.
profiler record start
# attendez qu’un « hitch warning » s’affiche, puis :
profiler record stop
profiler saveJSON hitch.json

Ouvrez le fichier dans Chrome (outils de développement, onglet Performance, chargement du profil), ou suivez le lien que donne profiler view. Cherchez le tick anormalement long : les blocs qui le remplissent portent le nom des ressources et des événements en cause.

  • Lisez les avertissements d’oxmysql. Toute requête plus lente que la convar mysql_slow_query_warning (200 ms par défaut) produit une ligne qui contient « took …ms to execute a query! », avec la ressource et la requête. Avec set mysql_ui true, la commande /mysql donne en jeu le détail par ressource aux comptes autorisés.
  • Côté joueur, l’équivalent est resmon 1 dans la console F8 : le coût de chaque ressource client, en millisecondes. Si les joueurs rament sans aucun hitch warning côté serveur, cherchez sur leur PC ou dans un script client.
  • Si rien ne ressort, procédez par élimination sur le serveur de test, une ressource retirée à la fois. Jamais sur le serveur ouvert, où arrêter une ressource à chaud casse le jeu des joueurs connectés.

Corriger selon la cause

Boucle trop lourde
Un Wait inconditionnel dans chaque boucle, réglé sur le besoin réel : une vérification par seconde suffit à la plupart des tâches serveur. Découpez un gros traitement sur plusieurs ticks, et préférez les événements à la surveillance en boucle.
Allocations
Gardez en cache ce qui change peu (liste des joueurs, groupes, identifiants) et rafraîchissez-le à intervalle fixe, au lieu de le reconstruire à chaque appel.
Base de données
Indexez les colonnes de vos WHERE et vérifiez avec EXPLAIN que l’index sert. Ne lisez que les colonnes utiles, groupez les requêtes, gardez en mémoire ce qui est relu sans arrêt. Sur le même serveur, un identifiant passé en nombre à une colonne texte indexée faisait ignorer l’index : requête 15 fois plus lente sur 40 000 lignes.
Tâches périodiques
N’écrivez que ce qui a changé, étalez les joueurs sur plusieurs secondes, décalez les tâches entre elles. Pour sauvegarder la base, mysqldump --single-transaction lit les tables InnoDB sans les verrouiller, de préférence aux heures creuses.
Machine
Des cœurs dédiés à fréquence élevée : le thread principal ne tourne que sur un cœur à la fois, sa vitesse compte plus que leur nombre. Sous Linux, la valeur st de top montre le temps processeur repris à votre VPS. Voir héberger un serveur FiveM.
Trafic réseau
Filtrez les attaques en amont (voir protéger un serveur FiveM contre le DDoS et les cheats). Côté scripts, créez le décor fixe en entités locales, et ne renvoyez pas chaque seconde un ordre qui n’a pas changé.

Vérifier que c’est réglé et éviter le retour

Comparez à charge égale, même tranche horaire et même nombre de joueurs : lignes « hitch warning » du journal de la console avant et après, graphique de txAdmin, nouvelle capture au profiler. Vérifiez au passage que ce journal s’écrit bien sur le disque : un fichier resté vide fausse toute comparaison.

Pour que l’avertissement ne revienne pas :

  • Mesurez chaque nouvelle ressource sur le serveur de test avant le serveur ouvert : une capture au profiler côté serveur, resmon 1 côté client.
  • Une seule modification par redémarrage. Au premier blocage, vous savez quoi retirer.
  • Surveillez les requêtes lentes signalées par oxmysql, et indexez au fil de l’eau.
  • Gardez de la marge processeur : un soir d’affluence charge bien plus que l’après-midi où vous testez.

Si vous préférez ne gérer ni la machine ni la base de données, GeoBase vend une base de serveur RP avec son hébergement.

Questions fréquentes

Un server thread hitch warning au démarrage du serveur est-il grave ?
Non. Quelques avertissements isolés pendant le chargement des ressources sont courants. Ils comptent quand ils reviennent avec des joueurs connectés.
Quelle différence entre server thread et network thread hitch warning ?
Le premier concerne le thread principal, qui exécute les scripts : la cause est le plus souvent une ressource. Le second concerne le thread réseau, qui échange les paquets avec les joueurs : regardez d’abord la machine et le trafic.
Un processeur plus puissant fait-il disparaître les hitch warnings ?
Il aide quand la machine est en cause. Il ne corrige pas un script qui bloque le thread : la ressource fautive continuera, un peu plus vite.
Peut-on désactiver le hitch warning dans le server.cfg ?
Aucun réglage ne le fait disparaître : FXServer l’écrit dès que le seuil est dépassé. Le masquer ne changerait rien pour les joueurs, qui subissent le blocage.

À lire ensuite