Resolver erros comuns no console FiveM: guia prático de debug

O console do FiveM é o ponto de partida pra qualquer debug sério. Ele acumula mensagens de erro em tempo real — algumas críticas, outras silenciosas — e ignorar essas linhas é o caminho mais rápido pra um servidor instável. Owners experientes leem o console toda vez que sobem um recurso novo; owners iniciantes só olham quando jogador reclama no Discord.

Este guia cobre os erros mais comuns que aparecem no console de um servidor FiveM em produção: script errors, dependências ausentes, manifests inválidos, falhas de banco e problemas de framework. Pra cada erro mostramos como identificar a causa real e aplicar a correção definitiva — não só calar a mensagem.

Tempo estimado de leitura e execução: 25 a 40 minutos, dependendo de quantos resources você precisa auditar.

Pré-requisitos

Antes de começar o debug você precisa de acesso ao servidor e capacidade de reiniciar resources individualmente.

Como ler uma mensagem de erro do console

Toda linha de erro do FiveM segue um padrão previsível. Aprender a decodificar essas mensagens economiza horas de tentativa-e-erro.

A estrutura geral é: prefixo de cor (^1 vermelho, ^3 amarelo), tipo de erro, resource afetado, arquivo e linha, descrição. Exemplo real:

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

A primeira linha diz o resource (meu_script), o arquivo (server/main.lua), a linha (42) e o tipo (attempt to index a nil value). As linhas com > são o stack trace — leia de cima pra baixo pra entender a cadeia de chamadas que levou ao erro.

Stack traces invertidos

O FiveM lista o frame mais recente primeiro (oposto do que Python ou Node fazem). A linha que disparou o erro é a primeira >, a função que chamou ela vem depois, e assim sucessivamente até o evento raiz.

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

O erro mais comum em servidores FiveM, especialmente após updates de framework ou atualizações de scripts customizados.

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 nao encontrado, evento ignorado'):format(source))
        return
    end
    player.setMoney(data.amount)
end)

restart myresource

Erro 2: Could not find dependency X for resource Y

Aparece quando o fxmanifest.lua de um resource declara dependência de outro que não está iniciado ou nem existe no 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 meus_scripts

Erro 3: Couldn’t load resource manifest

O servidor encontrou a pasta do resource mas falhou ao parsear o fxmanifest.lua. Tipicamente erro de sintaxe ou versão inválida.

fx_version 'cerulean'
game 'gta5'

author 'seu_nome'
description 'descrição do resource'
version '1.0.0'

server_scripts {
    'server/*.lua'
}

client_scripts {
    'client/*.lua'
}

Erro 4: Database connection failed (oxmysql)

Erros de banco aparecem como [oxmysql] [ERROR] Connection refused ou Access denied for user. Cada subtipo tem causa distinta.

Connection refused

O MySQL não está aceitando conexões no host/porta configurados.

# Confirme que o MySQL está rodando
systemctl status mysql

# Teste conectividade manual
mysql -h 127.0.0.1 -u fivem -p fivem_db

Se o MySQL roda em container Docker separado, o host na connection string deve ser o nome do container, não localhost.

Access denied

Credenciais incorretas no server.cfg:

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

Caracteres especiais na senha (@, #, /) precisam ser URL-encoded. Senha p@ss#1 vira p%40ss%231. Erro de encoding é causa frequente de “Access denied” mesmo com senha correta.

Pool timeout

[oxmysql] [ERROR] Pool is closed indica que conexões foram derrubadas (reinício do MySQL, timeout do servidor). Reinicie o resource:

restart oxmysql

Pra prevenir, configure wait_timeout no MySQL pra valor maior que o intervalo de queries do servidor.

Erro 5: Resource X failed to start

Falha genérica de inicialização. A causa real está nas linhas imediatamente acima da mensagem.

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

luac -p server/main.lua

Verificação

Depois de aplicar correções, confirme que o console está limpo executando esta sequência de verificação.

restart all

con_miniconChannels script:*

Resolução de problemas

Erro persiste após restart do resource

O resource pode ter cache em arquivo. Pare completamente, delete cache/ da raiz do servidor e suba de novo:

stop meu_resource
# pare o servidor
rm -rf cache/
# suba o servidor
ensure meu_resource

Console enche de erros idênticos a cada segundo

Algum loop está disparando o erro em cada tick. Identifique o resource pela primeira linha do erro e pare-o imediatamente:

stop nome_do_resource

Investigue o código offline antes de subir de novo — deixar rodando em loop pode derrubar performance do servidor inteiro.

Erro sem stack trace

Erros nativos do client (renderização, scaleform) muitas vezes não trazem trace. Use profiler record 500 no console do servidor e abra o profile em localhost:30120/profiler pra ver qual resource estava ativo no momento.

Próximos passos

Com o console limpo, considere os próximos níveis de hardening do servidor:

• Configure rotação de logs via sv_logFile pra preservar histórico de erros pós-restart e facilitar debug retroativo
• Adicione monitoramento contínuo do profiler em horários de pico pra detectar resources que degradam silenciosamente sem disparar erro
• Documente correções aplicadas num CHANGELOG por resource — quando o problema voltar daqui 6 meses, o histórico economiza horas
• Estabeleça processo de revisão de fxmanifest e dependências antes de subir qualquer resource novo pra produção

Se você está rodando um servidor FiveM em produção, uma VPS Hostini com hospedagem dedicada pra jogos garante recursos isolados, latência baixa pro Brasil e console acessível via txAdmin pré-configurado — sem disputar CPU com outros servidores no mesmo nó.