Dépannage : lire les erreurs et les corriger

Un serveur FiveM parle beaucoup. Presque tout ce qui ne marche pas est écrit quelque part : dans la console AMP au démarrage, ou dans la console F8 du joueur. Ce chapitre t'apprend à lire ces messages, puis te donne un catalogue des erreurs fréquentes avec cause et solution.

1. La méthode #

Quatre gestes, avant de chercher sur le forum.

Lire la console AMP au démarrage #

1. Ouvre Console dans AMP.
2. Clique sur Restart dans Status, puis lis en direct.
3. Cherche [ERROR], Could not, Failed, error, Warning. Les erreurs de démarrage arrivent dans les 30 premières secondes, pendant les Started resource ….
4. Note le nom de la ressource entre crochets en tête de ligne : [ script:ox_inventory ] te dit qui parle.

La console AMP ne garde que les dernières lignes. Pour l'historique : File Manager → AMP_Logs. Côté joueur, F8 garde tout depuis le lancement du jeu.

Isoler avec stop / start #

1. Tape stop <ressource> dans la console AMP pour la ressource ajoutée en dernier.
2. Reproduis le problème en jeu.
3. Si le problème disparaît, c'est elle. Sinon, start <ressource> et passe à la suivante.
4. Quand tu as trouvé, restart <ressource> et lis les lignes qui suivent.

Plus rapide que de retirer dix scripts d'un coup, et tu gardes ton ordre de ensure.

Regarder F8 côté client #

Affichage, menus, touches, MLO, véhicules : tout ça se passe chez le joueur, le serveur n'en voit rien.

1. Ouvre la console avec F8 dans le jeu.
2. Reproduis le problème.
3. Lis les lignes rouges : elles nomment la ressource et la ligne du fichier.
4. Copie le message exact : c'est lui que tu chercheras dans ce chapitre ou sur le forum.

Référence : https://docs.fivem.net/docs/client-manual/console-commands/

Reproduire avant de corriger #

Une erreur que tu ne sais pas déclencher, tu ne sauras pas vérifier qu'elle est corrigée. Note l'action, le joueur, le moment (connexion, spawn, menu). Corrige, puis refais exactement la même action.

✅ À retenir : console AMP au démarrage → stop/start pour isoler → F8 chez le joueur → reproduire. Toujours le message exact.

2. Catalogue des erreurs fréquentes #

Chaque fiche : le message tel qu'il apparaît → la cause → ce que tu fais.

Could not find gameName value in vehicles.meta for vehicle model X #

• Où : console serveur, au démarrage de qbx_core.
• Cause : le modèle X est listé dans vehicles.lua du framework mais absent du jeu chargé : DLC plus récent que ton Enforce Game Build, ou pack addon pas installé (ou pas encore démarré).
• Solution : sans gravité si tu n'attends pas cette voiture. Sinon : monte le build (chapitre 07, section 5) ou installe le pack addon avec son ensure avant le framework. Pour faire taire l'avertissement, retire la ligne dans vehicles.lua.

No such export X in resource Y #

• Où : console serveur ou F8.
• Cause : un script appelle exports['Y']:X() et Y n'a pas cet export. Trois cas : Y n'est pas démarrée (ordre des ensure), Y n'est pas la version attendue, ou Y est le nom fourni par provide et pas le vrai nom. Exemple : qbx_core fournit qb-core, mais l'export s'appelle par le vrai nom de la ressource.
• Solution : vérifie que Y est dans Starting Resources au-dessus de l'appelant. Ouvre fxmanifest.lua de Y et cherche exports/server_exports : si X n'y est pas, mets à jour selon la page du script. Si Y est un nom provide, remplace par le vrai nom du dossier.

attempt to index a nil value (field 'X' / global 'X') #

• Où : serveur ou F8, avec fichier et numéro de ligne.
• Cause : le script lit X.quelquechose alors que X est vide : dépendance pas encore démarrée (framework, ox_lib), clé de configuration supprimée ou mal orthographiée, joueur pas encore chargé.
• Solution : va à la ligne indiquée. Si X vient d'une autre ressource, remonte-la dans Starting Resources. Si X est une clé de config.lua, compare avec le fichier d'origine du script.

attempt to compare string with number (ou number with nil) #

• Où : serveur ou F8.
• Cause n°1 : un fichier de sauvegarde (main.lua.bak, server.lua.old) dans un dossier dont le manifeste charge server/** ou client/**. La copie s'exécute comme un script : événements doublés, variables écrasées.
• Cause n°2 : un nombre de config écrit entre guillemets (Config.Prix = "100").
• Solution : supprime tout .bak/.old/- Copie dans resources/, range tes sauvegardes dans server-data/sauvegardes/, puis refresh et restart <ressource>. Pour la config, retire les guillemets.

Resource X uses the deprecated … #

• Où : console serveur au démarrage.
• Cause : format ancien. La fin de la ligne dit lequel : __resource.lua au lieu de fxmanifest.lua, ou un fx_version dépassé. Référence : https://docs.fivem.net/docs/scripting-reference/resource-manifest/.
• Solution : avertissement, pas une panne. Cherche une version récente. Si le script est abandonné, renomme __resource.lua en fxmanifest.lua, ajoute fx_version 'cerulean' et game 'gta5' en tête, puis refresh et restart.

Unable to establish a connection to the database (ER_ACCESS_DENIED_ERROR) #

• Où : console serveur, au démarrage de oxmysql.
• Cause : utilisateur, mot de passe ou hôte faux dans mysql_connection_string. Sur TeamKit le mot de passe de la base est celui de ton compte AMP ; l'hôte est l'hôte « local » du tableau de bord teamkit.fr, pas l'IP publique.
• Solution : recopie la chaîne du tableau de bord telle quelle dans Additional Server Settings :

set mysql_connection_string "mysql://UTILISATEUR:MOT_DE_PASSE@HOTE:PORT/BASE?charset=utf8mb4"

Redémarre l'instance. Détail au chapitre 06.

ECONNREFUSED #

• Où : console serveur, oxmysql.
• Cause : hôte ou port faux. Le port de la base n'est pas 3306 : c'est celui affiché sur le tableau de bord pour ton serveur.
• Solution : corrige HOTE:PORT dans la chaîne de connexion, redémarre l'instance.

Server license key authentication failed #

• Où : console serveur, juste après le démarrage.
• Cause : clé absente, mal collée (espace en trop), révoquée, ou liée à une autre IP que celle de ton serveur TeamKit.
• Solution : sur https://portal.cfx.re/servers/registration-keys, crée une clé pour l'IP de ton serveur (celle du tableau de bord), colle-la dans Configuration → FiveM → Cfx.re Server Registration Key, Save, Restart. Une clé par serveur.

Could not load 'locales/fr.json' #

• Où : console serveur ou F8, à l'initialisation d'un script.
• Cause : tu as demandé la langue fr (souvent setr ox:locale fr) et cette ressource n'a pas de locales/fr.json. Ou le fichier existe mais n'est pas dans files du manifeste, ou son JSON est invalide.
• Solution : dans locales/, copie en.json en fr.json et traduis (ou laisse en anglais en attendant). Vérifie files { 'locales/*.json' } dans le manifeste, puis refresh et restart. Si le JSON est refusé, voir la fiche CRLF/UTF-8.

Oversized assets … WILL lead to streaming issues #

• Où : console serveur au démarrage d'un MLO ou d'un pack de véhicules.
• Cause : un fichier de plus de ~16 Mo dans stream/.
• Solution : ça fonctionne, mais des textures peuvent manquer chez certains joueurs. Demande à l'auteur une version optimisée ou accepte le défaut. Ne découpe pas le fichier toi-même.

Failed to fetch / erreurs de téléchargement côté joueur #

• Où : F8, ou écran d'erreur au chargement.
• Cause : le joueur n'arrive pas à télécharger un fichier. Soit le serveur ne répond pas sur 30120 en TCP (instance arrêtée, redémarrage en cours), soit une ressource charge un élément externe (ui_page en URL, police ou script sur un CDN) injoignable ou bloqué chez le joueur.
• Solution : vérifie que l'instance est Running dans Status et demande au joueur de relancer FiveM. Si l'erreur cite une URL externe, ouvre-la dans un navigateur : si elle est morte, remplace-la par une copie locale dans html/ déclarée dans files.

Le joueur reste bloqué à l'écran de chargement #

• Où : chez le joueur, sans message.
• Cause : un script client ne finit pas de charger : erreur Lua côté client (visible dans F8), boucle sans Wait, framework sans base de données (le joueur ne peut pas être créé), ou spawnmanager/sessionmanager retirés par erreur.
• Solution : le joueur ouvre F8 pendant le chargement et te copie les lignes rouges. Toi, vérifie dans la console AMP que oxmysql s'est connecté et que les ressources [system] de cfx-server-data sont toujours dans Starting Resources. Isole avec stop/start sur les derniers scripts client ajoutés.

Une ressource ne démarre pas #

• Messages : Couldn't find resource X, Could not start resource X, resource X has no manifest.
• Cause : fxmanifest.lua n'est pas à la racine du dossier (le zip a créé resources/monscript/monscript-main/), le nom du dossier ne correspond pas au ensure, ou le serveur n'a pas relu le dossier depuis l'upload.
• Solution :

1. Vérifie dans File Manager que resources/<nom>/fxmanifest.lua existe à ce niveau exact. Déplace les fichiers si un sous-dossier s'est glissé.
2. Tape refresh dans la console.
3. Tape ensure <nom> et lis la réponse.
4. Si dependency Y is not running : ajoute ou remonte Y dans Starting Resources, Save, Restart.

Modified client files (pure mode) #

• Où : chez le joueur, refus à la connexion, avec le nom du fichier modifié.
• Cause : ton serveur est en sv_pureLevel 1 ou 2 (Block Modified Client Files) et le joueur a des fichiers de jeu modifiés. Niveau 1 : seuls l'audio et les mods graphiques connus passent ; niveau 2 : rien. Référence : https://docs.fivem.net/docs/server-manual/server-commands/#sv_purelevel-level.
• Solution : le joueur retire le fichier nommé (ou vérifie son installation GTA), puis redémarre son jeu. Au premier changement de niveau, tout le monde doit relancer FiveM. Pour tolérer les packs graphiques, reste au niveau 1.

Doublons de ressources #

• Symptômes : deux inventaires, deux menus de vêtements, un MLO qui clignote, événements déclenchés deux fois, resource X already exists dans la console.
• Cause : deux dossiers du même nom dans deux catégories, ou deux scripts qui font la même chose (deux inventaires, deux HUD, deux MLO au même endroit).
• Solution : cherche le nom dans tout resources/. Un seul dossier par nom, une seule ressource par fonction. Supprime l'autre (après copie hors de resources/), refresh, Restart.

Sauvegardes .bak dans server/** #

• Symptômes : attempt to compare string with number, événements doublés, un script qui garde l'ancien comportement malgré tes modifications.
• Cause : main.lua.bak, main.lua.old, main - Copie.lua chargés par un joker server/** ou client/**.
• Solution : jamais de sauvegarde dans un dossier de ressource. Range-les dans server-data/sauvegardes/, puis refresh et restart.

Chaînes Lua multilignes côté client #

• Symptômes : le script passe côté serveur, mais le client plante ou le script client ne se charge pas. Dans F8 : unfinished string avec un numéro de ligne.
• Cause : une chaîne '...' ou "..." coupée par un vrai retour à la ligne. Le serveur la tolère, le client FiveM non. Un copier-coller depuis un forum en produit facilement.
• Solution : va à la ligne citée, remplace par des crochets longs ou une concaténation :

-- refusé côté client
local texte = 'Bonjour
ville'

-- accepté
local texte = [[Bonjour
ville]]
local texte2 = 'Bonjour' .. '\n' .. 'ville'

Caractères CRLF et UTF-8 dans les fichiers édités sous Windows #

• Symptômes : un JSON refusé (Unexpected token ou Could not load 'locales/fr.json'), un .lua qui échoue sur sa première ligne, des accents affichés en é.
• Cause : le Bloc-notes et certains éditeurs ajoutent une marque BOM en tête des fichiers UTF-8, ou enregistrent en ANSI. Lua tolère les fins de ligne Windows (CRLF), mais tous les lecteurs JSON ne tolèrent pas le BOM.
• Solution : édite avec l'éditeur du File Manager d'AMP, VS Code ou Notepad++. Enregistre en UTF-8 sans BOM, fins de ligne LF. Fichier déjà abîmé : « Convertir en UTF-8 sans BOM », enregistre, restart <ressource>.

Le serveur n'apparaît pas dans la liste #

• Symptômes : le serveur tourne, tes amis se connectent par connect ip:port dans F8, mais rien dans l'onglet Servers.
• Causes, dans l'ordre à vérifier :

1. Clé Cfx.re absente ou liée à une autre IP (fiche Server license key).
2. Project Name non conforme : plusieurs noms, tags, majuscules abusives → serveur masqué.
3. Mark Server Private coché : AMP écrit sv_master1 "", le serveur n'est plus joignable par la liste.
4. sets locale laissé sur une valeur d'exemple ; mets fr-FR ou fr-BE.
5. Port bloqué ou instance pas Running.
6. Zéro joueur depuis longtemps : la liste favorise l'activité. Connecte-toi à deux et attends quelques minutes.

• Solution : corrige dans Configuration → FiveM, Save, Restart, puis cherche ton Project Name dans le client FiveM. Voir chapitre 07, section 8.

✅ À retenir : lis la ressource nommée entre crochets, cherche le message exact dans ce catalogue, applique la solution, reproduis pour vérifier. Et un seul changement à la fois : trois scripts ajoutés d'un coup, tu ne sais plus lequel casse.

3. Demander de l'aide au staff TeamKit : quoi fournir #

Le staff ne voit pas ton écran. Un message complet est traité en une fois ; un message vague fait trois allers-retours. Fournis :

1. L'extrait de console du démarrage : de Restart jusqu'à la première erreur, plus les 20 lignes qui suivent. Du texte copié-collé, pas une photo.
2. Ton Starting Resources complet, copié depuis Configuration → FiveM, sans le mot de passe de la base.
3. Ce qui a changé depuis la dernière fois où ça marchait : script ajouté, fichier modifié, build changé, réglage touché, avec l'heure approximative.
4. Le message exact côté joueur (F8) et l'action qui le déclenche.
5. Ce que tu as déjà essayé : refresh, stop/start de quelle ressource, redémarrage de l'instance.

Où poster : le salon d'aide du Discord TeamKit ou un ticket depuis teamkit.fr. Ne colle jamais ta chaîne mysql_connection_string ni ta clé Cfx.re en public : remplace la valeur par xxx.

Pour qu'un membre du staff regarde directement, crée-lui un sous-compte Observateur (lecture de console) depuis le tableau de bord, et retire-le une fois le problème réglé.

✅ À retenir : console du démarrage + Starting Resources + ce qui a changé + message F8 + ce que tu as essayé. Sans mot de passe.

✅ Checklist du chapitre #

• Je sais ouvrir la console AMP et repérer la ressource nommée entre crochets.
• Je sais isoler une ressource avec stop / start sans toucher à Starting Resources.
• Je demande la console F8 pour tout problème d'affichage, de menu ou de chargement.
• J'ai vérifié qu'aucun .bak/.old ne traîne dans resources/.
• Ma chaîne MySQL vient du tableau de bord teamkit.fr, avec le bon port et l'hôte local.
• Ma clé Cfx.re est liée à l'IP de mon serveur TeamKit.
• Après un changement de manifeste : refresh puis restart. Après un changement de Configuration : Save puis Restart de l'instance.
• Mes fichiers sont enregistrés en UTF-8 sans BOM, mes chaînes Lua ne sont pas coupées par un retour à la ligne.
• Une seule ressource par fonction, un seul MLO par lieu, un seul dossier par nom.
• Mon message au staff contient la console du démarrage, Starting Resources et ce qui a changé.

❓ Si ça ne marche pas #

• Je ne trouve aucune erreur dans la console AMP. L'erreur est chez le joueur : ouvre F8 pendant l'action qui échoue. Si F8 est vide aussi, stop le dernier script ajouté et recommence.
• L'erreur nomme une ressource que je n'ai pas installée. C'est une ressource de base de cfx-server-data ([system], [managers]) ou une dépendance d'un script. Ne la supprime pas ; cherche qui l'appelle dans les dependencies des manifestes.
• Ça marchait hier, je n'ai rien changé. Un sous-compte Fichiers ou Technicien a peut-être modifié un fichier : regarde les dates dans File Manager. Ou un redémarrage planifié dans Schedule a relu une modification en attente.
• Le même message revient après correction. Tu n'as pas fait refresh avant restart (manifeste), ou pas redémarré l'instance (Configuration). Fais les deux, puis reproduis.
• Le serveur redémarre en boucle. Lis les dernières lignes avant chaque redémarrage dans AMP_Logs. Clé Cfx.re invalide ou base injoignable font quitter FXServer, et AMP le relance selon son réglage. Corrige la cause.
• J'ai tout essayé. Rassemble les cinq éléments de la section 3 et poste-les.