SCRIPT ERROR FiveM : le lire et corriger la ressource

La console de chaque serveur FiveM affiche des lignes SCRIPT ERROR en rouge, et un serveur très fréquenté en imprime des centaines par jour. La plupart viennent d’une poignée d’erreurs qui se répètent d’une ressource à l’autre. Ce guide montre comment en lire une, ce que signifient les messages courants et comment trouver les quelques erreurs à corriger en premier.

Comment lire un SCRIPT ERROR

[ script:qb-garages] SCRIPT ERROR: @qb-garages/server/main.lua:57: attempt to index a nil value (local 'Player')
[ script:qb-garages] > handler (@qb-garages/server/main.lua:57)

• @qb-garages est la ressource, server/main.lua le fichier qu’elle contient et 57 la ligne.
• Le texte après le numéro de ligne est l’erreur Lua. Entre parenthèses, Lua nomme la variable : local 'Player' signifie qu’une variable locale appelée Player contenait nil.
• Les lignes qui commencent par > forment la pile d’appels, l’appel le plus récent en premier. Quand la première ligne pointe vers un framework ou une bibliothèque comme es_extended ou oxmysql, descendez jusqu’à la première ligne située dans une ressource que vous gérez vous-même. C’est en général là que la mauvaise valeur est née.

Les erreurs courantes et leurs correctifs

attempt to index a nil value

Le script lit un champ sur quelque chose qui n’existe pas. Sur ESX et QBCore, c’est presque toujours l’objet joueur, récupéré pour un joueur déjà parti ou qui n’a pas fini de charger :

local Player = QBCore.Functions.GetPlayer(source)
if not Player then return end
local cash = Player.PlayerData.money.cash

La vérification de la deuxième ligne est le correctif, et c’est pareil pour ESX.GetPlayerFromId(source). Quand le message nomme un champ, comme dans (field 'PlayerData'), la table au-dessus existe mais n’a pas cette clé, ce qui signifie souvent qu’un script a été écrit pour une autre version du framework.

attempt to call a nil value

Le script appelle une fonction qui n’existe pas, et la parenthèse la nomme : (field 'GetPlayerData') ou (method 'addMoney'). Les causes habituelles sont une fonction que le framework a renommée dans une mise à jour, une ressource qui la définit mais démarre plus tard, ou une globale comme ESX qui n’a jamais été définie. Les versions récentes d’ESX fournissent leur objet via exports['es_extended']:getSharedObject() ou @es_extended/imports.lua, et un script qui attend encore l’ancien événement esx:getSharedObject peut se retrouver sans lui.

No such export in resource

No such export SendAlert in resource ps-mdt signifie qu’un script a appelé exports['ps-mdt']:SendAlert() et que ps-mdt n’a pas d’export de ce nom, du moins pas encore. Soit la ressource n’a pas démarré, soit elle tourne sous un autre nom de dossier, soit l’export a été renommé. Placez la ressource qui fournit l’export plus haut dans server.cfg et vérifiez le nom dans son fxmanifest.lua ou sa documentation.

attempt to perform arithmetic on a nil value

Quelque chose comme count + 1 où count vaut nil, en général une valeur lue dans la base de données ou une clé de config qui n’existe pas. Donnez-lui une valeur par défaut là où elle est lue : local count = row.count or 0.

attempt to compare number with nil

La même cause dans une comparaison : if amount > Config.Limit alors que Limit manque dans votre config. Vérifiez que chaque clé lue par le script existe dans votre copie de config.lua, surtout après une mise à jour qui en a ajouté de nouvelles.

Erreurs des ressources JavaScript

Les ressources JavaScript affichent SCRIPT ERROR: suivi d’une erreur JavaScript et d’une pile at. TypeError: Cannot read properties of undefined (reading 'citizenid') est la version JavaScript de l’indexation de nil, et elle demande la même vérification.

Error running system event handling function

Cette ligne signifie qu’un gestionnaire d’un événement intégré comme playerDropped ou onResourceStart a levé une erreur. Les lignes en dessous nomment le fichier et la ligne, comme pour un SCRIPT ERROR normal.

Quelles erreurs corriger en premier

Une console avec cinq cents erreurs en contient en général vingt différentes. Corrigez-les selon leur impact : d’abord l’erreur qui a touché le plus de joueurs, puis tout ce qui est nouveau depuis le dernier redémarrage, c’est-à-dire souvent la mise à jour que vous venez de déployer. Si la console est enregistrée dans un fichier, cette commande compte les erreurs par emplacement :

grep -o 'SCRIPT ERROR: @[^:]*:[0-9]*' console.log | sort | uniq -c | sort -rn | head -20

Elle ne compte que des lignes : un seul joueur bloqué dans une boucle peut faire monter en tête une erreur inoffensive, et une erreur bruyante d’hier a le même aspect qu’une erreur apparue il y a une heure.

Laissez FiveDock les regrouper

L’agent FiveDock lit la console du serveur au fur et à mesure qu’elle s’affiche. Il associe chaque SCRIPT ERROR à sa pile d’appels, masque les noms de joueurs, les adresses IP et les identifiants, et regroupe les erreurs par ressource, fichier, ligne et message, en ignorant les nombres dans le message pour qu’un même bug ne compte qu’une fois.

Sur Metro, Error Hunter liste ces groupes avec un compteur, le nombre de joueurs touchés et la date de première et de dernière apparition de chaque erreur, avec tout ce qui est nouveau depuis le redémarrage en haut. Deploy Guard fait une sauvegarde avant un redémarrage, rend un verdict dix minutes après et nomme la ressource à l’origine des nouveaux problèmes.

Questions fréquentes

Que signifie attempt to index a nil value dans FiveM ?

Le script a essayé de lire un champ d’une variable qui vaut nil, et le nom entre parenthèses indique laquelle. Sur ESX et QBCore, c’est en général un objet joueur récupéré pour un joueur déconnecté ou pas encore chargé, et le correctif est de vérifier que l’objet existe avant de l’utiliser.

Comment trouver quelle ressource provoque un SCRIPT ERROR ?

La ressource est le nom après @ au début de l’emplacement, comme dans @qb-garages/server/main.lua:57. S’il s’agit d’un framework ou d’une bibliothèque, lisez les lignes de la pile qui commencent par > jusqu’à la première située dans une ressource que vous gérez vous-même.

Pourquoi des SCRIPT ERROR apparaissent-ils après la mise à jour d’une ressource ?

Les mises à jour renomment des fonctions et des exports, ajoutent des clés de config et exigent des versions plus récentes du framework. Comparez le nouveau config.lua avec le vôtre, cherchez dans le changelog les exports renommés et redémarrez les ressources qui dépendent de celle que vous avez mise à jour.

Puis-je masquer les SCRIPT ERROR dans la console ?

Vous pouvez entourer les appels d’un pcall, mais cela cache le bug et laisse en place ce qu’il a cassé. Corrigez la valeur nil à sa source et regroupez les erreurs pour voir lesquelles comptent.