Cómo resolver errores comunes de la consola de FiveM: guía práctica de debug

La consola de FiveM es el punto de partida para cualquier debug serio. Acumula mensajes de error en tiempo real — algunos críticos, otros silenciosos — e ignorar esas líneas es el camino más rápido hacia un servidor inestable. Los owners experimentados leen la consola cada vez que suben un recurso nuevo; los owners iniciantes solo miran cuando algún jugador se queja en Discord.

Esta guía cubre los errores más comunes que aparecen en la consola de un servidor FiveM en producción: script errors, dependencias ausentes, manifests inválidos, fallos de base de datos y problemas de framework. Para cada error mostramos cómo identificar la causa real y aplicar la corrección definitiva — no solo callar el mensaje.

Tiempo estimado de lectura y ejecución: 25 a 40 minutos, dependiendo de cuántos resources necesites auditar.

Requisitos previos

Antes de empezar el debug necesitas acceso al servidor y la capacidad de reiniciar resources individualmente.

Cómo leer un mensaje de error de la consola

Cada línea de error de FiveM sigue un patrón predecible. Aprender a decodificar esos mensajes ahorra horas de prueba y error.

La estructura general es: prefijo de color (^1 rojo, ^3 amarillo), tipo de error, resource afectado, archivo y línea, descripción. Ejemplo real:

[       script:mi_script] SCRIPT ERROR: @mi_script/server/main.lua:42: attempt to index a nil value (local 'player')
> CreatePlayer (@mi_script/server/main.lua:42)
> handler (@mi_script/server/events.lua:18)

La primera línea indica el resource (mi_script), el archivo (server/main.lua), la línea (42) y el tipo (attempt to index a nil value). Las líneas con > son el stack trace — léelas de arriba abajo para entender la cadena de llamadas que llevó al error.

Stack traces invertidos

FiveM lista el frame más reciente primero (al revés de lo que hacen Python o Node). La línea que disparó el error es la primera >, la función que la llamó viene después, y así sucesivamente hasta el evento raíz.

Error 1: SCRIPT ERROR — attempt to index a nil value

El error más común en servidores FiveM, especialmente tras updates del framework o actualizaciones de scripts personalizados.

RegisterServerEvent('myresource:save')
AddEventHandler('myresource:save', function(data)
    local player = ESX.GetPlayerFromId(source)
    player.setMoney(data.amount)
end)

RegisterServerEvent('myresource:save')
AddEventHandler('myresource:save', function(data)
    local player = ESX.GetPlayerFromId(source)
    if not player then
        print(('[myresource] Player %s no encontrado, evento ignorado'):format(source))
        return
    end
    player.setMoney(data.amount)
end)

restart myresource

Error 2: Could not find dependency X for resource Y

Aparece cuando el fxmanifest.lua de un resource declara dependencia de otro que no está iniciado o ni siquiera existe en el servidor.

Could not find dependency oxmysql for resource es_extended.
Couldn't start resource es_extended.

ls resources/ | grep oxmysql

ensure oxmysql
ensure es_extended
ensure esx_menu_default
ensure mis_scripts

Error 3: Couldn’t load resource manifest

El servidor encontró la carpeta del resource pero falló al parsear el fxmanifest.lua. Típicamente un error de sintaxis o versión inválida.

fx_version 'cerulean'
game 'gta5'

author 'tu_nombre'
description 'descripción del resource'
version '1.0.0'

server_scripts {
    'server/*.lua'
}

client_scripts {
    'client/*.lua'
}

Error 4: Database connection failed (oxmysql)

Los errores de base aparecen como [oxmysql] [ERROR] Connection refused o Access denied for user. Cada subtipo tiene causa distinta.

Connection refused

MySQL no está aceptando conexiones en el host/puerto configurados.

# Confirma que MySQL está corriendo
systemctl status mysql

# Prueba conectividad manual
mysql -h 127.0.0.1 -u fivem -p fivem_db

Si MySQL corre en un contenedor Docker separado, el host en la connection string debe ser el nombre del contenedor, no localhost.

Access denied

Credenciales incorrectas en server.cfg:

set mysql_connection_string "mysql://fivem:[email protected]:3306/fivem_db?charset=utf8mb4"

Los caracteres especiales en la contraseña (@, #, /) necesitan estar URL-encoded. La contraseña p@ss#1 queda como p%40ss%231. Un error de encoding es causa frecuente de “Access denied” incluso con contraseña correcta.

Pool timeout

[oxmysql] [ERROR] Pool is closed indica que las conexiones se cayeron (reinicio de MySQL, timeout del servidor). Reinicia el resource:

restart oxmysql

Para prevenirlo, configura wait_timeout en MySQL a un valor mayor que el intervalo de queries del servidor.

Error 5: Resource X failed to start

Fallo genérico de inicialización. La causa real está en las líneas inmediatamente anteriores al mensaje.

[script:mi_resource] Error loading script server/main.lua in resource mi_resource: server/main.lua:1: unexpected symbol near '<'
Failed to load script server/main.lua.
[c-scripting-core] Failed to start resource mi_resource

luac -p server/main.lua

Verificación

Después de aplicar las correcciones, confirma que la consola está limpia ejecutando esta secuencia de verificación.

restart all

con_miniconChannels script:*

Resolución de problemas

El error persiste tras reiniciar el resource

El resource puede tener caché en archivo. Detenlo completamente, borra cache/ de la raíz del servidor y súbelo de nuevo:

stop mi_resource
# detén el servidor
rm -rf cache/
# sube el servidor
ensure mi_resource

La consola se llena de errores idénticos cada segundo

Algún loop está disparando el error en cada tick. Identifica el resource por la primera línea del error y deténlo de inmediato:

stop nombre_del_resource

Investiga el código offline antes de subirlo otra vez — dejarlo corriendo en loop puede tumbar el rendimiento de todo el servidor.

Error sin stack trace

Los errores nativos del cliente (renderizado, scaleform) muchas veces no traen trace. Usa profiler record 500 en la consola del servidor y abre el profile en localhost:30120/profiler para ver qué resource estaba activo en ese momento.

Próximos pasos

Con la consola limpia, considera los próximos niveles de hardening del servidor:

• Configura rotación de logs vía sv_logFile para preservar el histórico de errores tras restart y facilitar debug retroactivo
• Agrega monitoreo continuo del profiler en horas pico para detectar resources que se degradan silenciosamente sin disparar error
• Documenta las correcciones aplicadas en un CHANGELOG por resource — cuando el problema vuelva en 6 meses, el histórico ahorra horas
• Establece un proceso de revisión de fxmanifest y dependencias antes de subir cualquier resource nuevo a producción

Si tienes un servidor FiveM en producción, una VPS Hostini con hosting dedicado para juegos garantiza recursos aislados, latencia baja para Latam y consola accesible vía txAdmin preconfigurado — sin competir por CPU con otros servidores en el mismo nodo.