SCRIPT ERROR en FiveM: cómo leerlo y arreglar el recurso

La consola de todo servidor de FiveM imprime líneas rojas de SCRIPT ERROR, y un servidor con mucha actividad puede sacar cientos al día. La mayoría vienen de un puñado de errores que se repiten entre recursos. Esta guía muestra cómo leer uno, qué significan los mensajes más comunes y cómo encontrar los pocos errores que conviene arreglar primero.

Cómo leer 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 es el recurso, server/main.lua el archivo dentro de él y 57 la línea.
• El texto después del número de línea es el error de Lua. Entre paréntesis, Lua nombra la variable: local 'Player' significa que una variable local llamada Player contenía nil.
• Las líneas que empiezan por > son la pila de llamadas, con la más reciente primero. Cuando la primera línea apunta a un framework o una librería como es_extended u oxmysql, sigue leyendo hacia abajo hasta la primera línea de un recurso que gestionas tú. Normalmente ahí es donde nació el valor incorrecto.

Errores comunes y cómo arreglarlos

attempt to index a nil value

El script lee un campo de algo que no existe. En ESX y QBCore casi siempre es el objeto del jugador, obtenido para un jugador que ya se ha ido o que aún no ha terminado de cargar:

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

La comprobación de la segunda línea es el arreglo, y lo mismo vale para ESX.GetPlayerFromId(source). Cuando el mensaje nombra un campo, como en (field 'PlayerData'), la tabla que hay encima existe pero no tiene esa clave, lo que a menudo significa que el script se escribió para otra versión del framework.

attempt to call a nil value

El script llama a una función que no existe, y el paréntesis la nombra: (field 'GetPlayerData') o (method 'addMoney'). Las causas habituales son una función que el framework renombró en una actualización, un recurso que la define pero arranca más tarde, o una global como ESX que nunca se asignó. El ESX nuevo entrega su objeto con exports['es_extended']:getSharedObject() o @es_extended/imports.lua, y un script que aún espera el evento antiguo esx:getSharedObject puede quedarse sin él.

No such export in resource

No such export SendAlert in resource ps-mdt significa que un script llamó a exports['ps-mdt']:SendAlert() y ps-mdt no tiene ningún export con ese nombre, al menos todavía. O el recurso no ha arrancado, o se ejecuta con otro nombre de carpeta, o el export cambió de nombre. Pon el recurso que ofrece el export antes en server.cfg y comprueba el nombre en su fxmanifest.lua o en su documentación.

attempt to perform arithmetic on a nil value

Algo como count + 1 donde count es nil, normalmente un valor leído de la base de datos o una clave de configuración que no existe. Dale un valor por defecto donde se lee: local count = row.count or 0.

attempt to compare number with nil

La misma causa en una comparación: if amount > Config.Limit cuando Limit falta en tu config. Comprueba que cada clave que lee el script existe en tu copia de config.lua, sobre todo después de una actualización que añadió claves nuevas.

Errores de recursos de JavaScript

Los recursos de JavaScript imprimen SCRIPT ERROR: seguido de un error de JavaScript y una pila at. TypeError: Cannot read properties of undefined (reading 'citizenid') es la versión de JavaScript de indexar nil, y se arregla con la misma comprobación.

Error running system event handling function

Esta línea significa que un manejador de un evento integrado como playerDropped o onResourceStart lanzó un error. Las líneas de debajo nombran el archivo y la línea, igual que en un SCRIPT ERROR normal.

Qué errores arreglar primero

Una consola con quinientos errores suele contener veinte distintos. Arréglalos por impacto: primero el error que afectó a más jugadores, luego todo lo nuevo desde el último reinicio, que normalmente es la actualización que acabas de subir. Con la consola guardada en un archivo, esto cuenta los errores por ubicación:

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

Solo cuenta líneas, así que un jugador atascado en un bucle puede subir al primer puesto un error inofensivo, y un error ruidoso de ayer se ve igual que uno que empezó hace una hora.

Deja que FiveDock los agrupe

El agente de FiveDock lee la consola del servidor a medida que imprime. Une cada SCRIPT ERROR con su pila, enmascara nombres de jugadores, direcciones IP e identificadores, y agrupa los errores por recurso, archivo, línea y mensaje, ignorando los números del mensaje para que el mismo bug cuente una sola vez.

En Metro, Error Hunter lista esos grupos con un contador, el número de jugadores afectados y cuándo se vio cada uno por primera y por última vez, con lo nuevo desde el reinicio arriba. Deploy Guard hace una copia de seguridad antes de un reinicio, da un veredicto diez minutos después y nombra el recurso detrás de cualquier problema nuevo.

Preguntas frecuentes

¿Qué significa attempt to index a nil value en FiveM?

El script intentó leer un campo de una variable que es nil, y el nombre entre paréntesis indica cuál. En ESX y QBCore suele ser un objeto de jugador obtenido para alguien que se desconectó o aún no ha cargado, y el arreglo es comprobar que el objeto existe antes de usarlo.

¿Cómo encuentro qué recurso causa un SCRIPT ERROR?

El recurso es el nombre que va tras @ al principio de la ubicación, como en @qb-garages/server/main.lua:57. Si es un framework o una librería, lee las líneas de la pila que empiezan por > hasta llegar a la primera de un recurso que gestionas tú.

¿Por qué aparecen SCRIPT ERROR después de actualizar un recurso?

Las actualizaciones renombran funciones y exports, añaden claves de configuración y esperan versiones más nuevas del framework. Compara el nuevo config.lua con el tuyo, busca en el changelog los exports renombrados y reinicia los recursos que dependen del que actualizaste.

¿Puedo ocultar los SCRIPT ERROR de la consola?

Puedes envolver las llamadas en pcall, pero eso esconde el bug y deja sin arreglar lo que rompió. Corrige el valor nil donde se origina y agrupa los errores para ver cuáles importan.