Diagnostiquer et résoudre un crash FiveM

Introduction

Un crash FiveM peut venir de :

• Une ressource cassée (script Lua/JS qui throw, dépendance manquante)
• Un artifact corrompu ou obsolète
• Une fuite mémoire (OOM kill par le kernel)
• Un plantage MySQL (perte de connexion oxmysql)
• Un assertion failed dans le natif Cfx
• Un anti-cheat ou ESX/QB corrompu

Ce guide vous donne la méthodologie pour identifier la cause en moins de 10 minutes.

Étape 1 : Identifier précisément le moment du crash

Avant de plonger dans les logs, posez-vous ces questions :

• Le crash arrive-t-il au démarrage ou en cours de partie ?
• Y a-t-il un pattern (un événement particulier, une commande, un script utilisé) ?
• Combien de joueurs étaient connectés ?
• Est-ce arrivé après une mise à jour (artifact, ressource, etc.) ?

Le crash a-t-il un délai constant (toujours après X heures = fuite mémoire) ou aléatoire (souvent une ressource buguée) ?

Étape 2 : Inspecter les logs txAdmin

txAdmin conserve l'historique des crashes :

Panel txAdmin → System → Logs

Vous verrez :

• Server Log : logs de la console FiveM
• Action Log : actions admin (ban, kick, etc.)
• CrashHandler Log : informations spécifiques aux crashes

Cherchez la ligne juste avant le crash :

[script:RESOURCE] SCRIPT ERROR: @ressource/server.lua:42: attempt to index a nil value

Ça vous dit immédiatement :

• Quelle ressource a crashé (RESOURCE)
• Quel fichier (server.lua ligne 42)
• Quelle erreur (attempt to index a nil value)

Étape 3 : Activer le mode verbose dans server.cfg

Ajoutez ces lignes dans server.cfg pour avoir plus de détails :

# Verbose général
sv_debugQueue 1
sv_enforceGameBuild 2944  # ou plus récent
set onesync on
set sv_debugScripts true

# Logs des hangs (freezes longs)
set sv_scriptHookAllowed 0

Redémarrez le serveur.

Étape 4 : Cas concret — Erreur "Couldn't load resource"

Couldn't load resource oxmysql: failure to load schema

Cause : la ressource oxmysql ne se charge pas, généralement à cause d'une mauvaise version Node.js (oxmysql 2.x demande Node 18+) ou d'une chaîne de connexion MySQL malformée.

Solution :

# Vérifier que MariaDB est joignable
sudo systemctl status mariadb
mysql -u fivem -p -e "SELECT 1;"

Inspectez la chaîne de connexion dans server.cfg :

set mysql_connection_string "server=localhost;database=fivem;userid=fivem;password=MotDePasse"

Attention aux caractères spéciaux dans le mot de passe (@, !, & etc.) : ils doivent être URL-encodés ou échappés.

Étape 5 : Cas concret — "FX has hung"

The server has been running for 60 seconds without responding.

Cause : un script bloque la thread principale (boucle infinie, opération synchrone bloquante, blocage I/O).

Solution : isolez la ressource fautive.

1. Démarrez le serveur sans aucune ressource custom (mettez # devant tous les ensure dans server.cfg)
2. Démarrez les ressources une par une en surveillant la console
3. La ressource qui déclenche le hang est identifiée

Étape 6 : Cas concret — Crash OOM (out of memory)

Sur Linux, vérifiez :

sudo dmesg | grep -i "killed process"

Si vous voyez :

Out of memory: Killed process 1234 (FXServer)

Cause : votre VPS n'a pas assez de RAM. FiveM consomme typiquement :

• 1 GB pour le serveur de base
• 2 GB avec ESX/QBCore
• 4-8 GB avec 32+ joueurs et beaucoup de ressources

Solution : passez à un VPS avec plus de RAM (VeryCloud propose des VPS Ryzen 8 GB à 16 GB pour ces usages).

En attendant, ajoutez du swap :

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Étape 7 : Cas concret — Crash artifact

FXServer.exe has triggered a breakpoint.

Cause : l'artifact FiveM est buggé ou incompatible avec votre OS.

Solution : changez d'artifact build.

1. Allez sur https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/
2. Évitez le tout dernier build (latest), prenez celui marqué recommended (généralement 2-3 builds en arrière, plus stable)
3. Téléchargez et remplacez :

cd ~/server
rm -rf alpine FXServer run.sh
wget https://runtime.fivem.net/artifacts/fivem/build_proot_linux/master/XXXX-XXXX/fx.tar.xz
tar xf fx.tar.xz && rm fx.tar.xz

Étape 8 : Cas concret — Erreur "C-stack overflow"

sol3 / C-stack overflow

Cause : une ressource Lua fait des appels récursifs sans condition d'arrêt.

Solution : c'est presque toujours une ressource custom. Désactivez-les une par une (voir étape 5) jusqu'à trouver le coupable. Puis inspectez le code Lua et cherchez les boucles non bornées.

Étape 9 : Analyser les dumps minidump

FiveM génère des minidumps lors de crashes critiques. Sur Linux :

ls -lh ~/.fivem/data/cache/
ls -lh ~/.fivem/data/server-cache-priv/CitizenFX_Server_*.dmp

Ces fichiers peuvent être ouverts avec gdb :

sudo apt install -y gdb
gdb ~/server/FXServer ~/.fivem/data/server-cache-priv/CitizenFX_Server_XXXX.dmp
(gdb) bt

La stack trace montre le natif qui a crashé. Si le crash vient d'une fonction Cfx native, ouvrez un ticket sur https://forum.cfx.re avec le dump.

Étape 10 : Outils complémentaires

txAdmin Live Console

Le live console est votre meilleur ami : il affiche en temps réel les erreurs Lua sans avoir à parser des fichiers logs.

profiler intégré FiveM

Tapez dans la console serveur :

profiler record 1000

Au bout de 1000 frames, tapez :

profiler view

Vous obtenez les ressources qui consomment le plus de CPU.

Inspection des ressources lentes

Dans la console :

resmon

Affiche un dashboard temps réel du CPU/mémoire par ressource.

Dépannage des erreurs MySQL spécifiques

"User space is full"

Cette erreur survient quand vous avez plus de tables / colonnes par utilisateur que la limite InnoDB par défaut. Solution :

SET GLOBAL innodb_file_per_table = ON;
ALTER TABLE table_name ROW_FORMAT=DYNAMIC;

Ou augmentez la limite dans /etc/mysql/mariadb.conf.d/50-server.cnf :

[mysqld]
innodb_buffer_pool_size = 1G
innodb_log_file_size = 256M

Redémarrez MariaDB :

sudo systemctl restart mariadb

"Too many connections"

ERROR 1040 (HY000): Too many connections

Augmentez dans /etc/mysql/mariadb.conf.d/50-server.cnf :

[mysqld]
max_connections = 500

Commandes utiles

# Logs en direct
sudo journalctl -u fivem -f

# Consommation CPU/RAM par processus
top -p $(pgrep -f FXServer)

# Mémoire utilisée par FiveM
ps -o pid,user,%mem,rss,command -p $(pgrep -f FXServer)

# Tester la connectivité MySQL depuis le user fivem
sudo -u fivem mysql -u fivem -p -e "SELECT 1;"

# Voir les derniers crashes système
sudo dmesg | tail -50

# Vérifier l'espace disque (un disque plein crash FiveM)
df -h

Conclusion

90% des crashes FiveM se résolvent en suivant cette méthodologie :

1. Identifier le moment (démarrage / runtime / OOM)
2. Lire les logs txAdmin
3. Désactiver les ressources une par une si nécessaire
4. Vérifier MySQL et la RAM
5. Mettre à jour les artifacts si rien ne marche

Pour les cas vraiment complexes, l'équipe support VeryCloud aide à diagnostiquer (ouvrir un ticket avec les 100 dernières lignes du log + le contexte).

Ressources

• Documentation crash troubleshooting FiveM : https://docs.fivem.net/docs/server-manual/troubleshooting
• Forum FiveM (recherche par message d'erreur) : https://forum.cfx.re
• Tuto VeryCloud — Installer FiveM + txAdmin : /docs/article/fivem-txadmin-install
• Tuto VeryCloud — Migration FiveM : /docs/article/migrate-fivem-vps