Cómo leer un ERROR DE SCRIPT de FiveM: archivo, línea y stack trace

Un error típico en la consola:

SCRIPT ERROR: @my_script/server/main.lua:42: attempt to index a nil value (local 'xPlayer')
> handler (@my_script/server/main.lua:42)
> ref (citizen:/scripting/lua/scheduler.lua:...)

Se parece a ruido, pero cada parte tiene un significado, y generalmente te dice exactamente dónde buscar. Esta guía muestra cómo leerlo, dónde encontrarlo, y qué hacer cuando no es suficiente.

#La primera línea: qué, dónde y por qué

SCRIPT ERROR: @my_script/server/main.lua:42: attempt to index a nil value (local 'xPlayer')

• SCRIPT ERROR: marca un error de Lua en un script. El script sigue ejecutándose después, pero el código que falló se detiene en esa línea.
• @my_script/server/main.lua es el nombre del recurso (my_script) y la ruta del archivo dentro de la carpeta del recurso.
• :42 es el número de línea en ese archivo.
• El resto es el mensaje: attempt to index a nil value (local 'xPlayer'). Lua lo lee así: en la línea 42 intentaste usar algo dentro de xPlayer, pero xPlayer es nil.

Abre el archivo, ve a esa línea, y mira las variables que esa línea usa. En la mayoría de los casos la respuesta ya está allí. Los mensajes comunes tienen sus propias guías: intento de llamar a un valor nil e intento de comparar nil.

#El stack trace: cómo el código llegó allí

Las líneas que comienzan con > son el stack trace. Enumera las funciones que se estaban ejecutando, desde la que falla hacia abajo hasta la que la inició:

> handler (@my_script/server/main.lua:42)
> ref (citizen:/scripting/lua/scheduler.lua:...)

La primera línea después del error es el mismo lugar que el error. Las líneas debajo muestran quién llamó a esa función. Cuando el error está dentro de una biblioteca u otro recurso, una línea de tu propio script más abajo en la lista a menudo es la causa real, porque tu script pasó un valor incorrecto en él.

Las líneas que comienzan con citizen:/scripting/lua/... (por ejemplo citizen:/scripting/lua/scheduler.lua) pertenecen a FiveM en sí. Son parte de la maquinaria que ejecuta tus eventos y threads. Puedes ignorarlas: el error nunca se arregla allí, y solo muestran que un thread o un evento se estaba ejecutando.

#Cliente o servidor: dónde buscar

Un error de script aparece en el lado donde se ejecuta el código:

• Scripts de cliente (client_scripts, archivos en una carpeta client): presiona F8 en el juego para abrir la consola del cliente. Si no ves nada, desplázate hacia arriba, ya que los errores pueden alejarse rápidamente.
• Scripts de servidor (server_scripts, archivos en una carpeta server): lee la consola del servidor. En txAdmin, esa es la página Live Console. En un servidor iniciado desde una terminal, es esa ventana de terminal.
• Scripts compartidos se ejecutan en ambos lados, así que el error puede aparecer en cualquier lugar.

Consejo: si un menú o una acción no hace nada y F8 está vacío, comprueba la consola del servidor. El código que falla puede estar del lado del servidor.

#Qué línea mirar

1. Lee el mensaje primero: dice qué tipo de problema es (nil, un tipo incorrecto, una exportación faltante).
2. Abre el archivo y línea de la primera línea. Comprueba cada variable en él.
3. Si el archivo pertenece a una biblioteca (ox_lib, el framework), baja el stack trace hasta que llegues a una línea del script que estás arreglando.
4. Comprueba si el error aparece una vez o constantemente. Un error constante en un bucle inunda la consola. Arregla ese primero, ya que oculta otros mensajes.

Los errores con el texto No such export o could not find dependency son diferentes. Se trata de recursos, no de líneas de código. Consulta no se pudo encontrar dependencia.

#Cuando la línea no es suficiente: añadir prints

Si la línea usa varias variables y no sabes cuál es nil, imprime cada una justo antes:

print('xPlayer:', xPlayer)
print('source:', source, type(source))
print('data:', json.encode(data))

Ejecuta el código nuevamente y lee la consola. Algunos consejos para prints útiles:

• Imprime el tipo así como el valor: type(value) muestra nil, number, string, table o function.
• Usa json.encode(table) para ver el interior de una tabla. Un print(table) simple solo muestra una dirección de memoria.
• Pon una etiqueta corta al frente, así puedas encontrar la línea en una consola ocupada.
• Imprime en el inicio de una función, para confirmar que se ejecuta en absoluto.

Elimina los prints una vez que el problema esté arreglado, ya que cuestan rendimiento en bucles ocupados.

#Dónde un error no aparece

• Scripts en depósito ocultan su código. El error te da un nombre de archivo, pero el archivo está encriptado y no puedes leer la línea. Contacta al autor con el texto de error completo.
• Errores de NUI (el menú en sí, escrito en HTML y JavaScript) no aparecen en F8 como SCRIPT ERROR. Abre las herramientas de desarrollador de NUI para leerlas: el comando nui_devtools en la consola F8 los abre en una pestaña del navegador.
• Errores en los primeros segundos: cuando inicias el servidor, los errores de recursos que fallan al cargar pueden pasar rápidamente. Busca en la consola o desplázate hacia arriba, o reinicia solo ese recurso y observa.

#Qué enviar cuando pides ayuda

Copia el error completo, el stack trace incluido, como texto, y di si viene de F8 o de la consola del servidor. Añade la línea de código a la que apunta y el framework que usas. Una captura de pantalla de una línea recortada no es suficiente para que nadie te ayude.

#Lista de verificación