SCRIPT ERROR no FiveM: como ler e corrigir o recurso

O console de todo servidor FiveM imprime linhas vermelhas de SCRIPT ERROR, e um servidor movimentado imprime centenas por dia. A maioria vem de um punhado de erros que se repetem entre recursos. Este guia mostra como ler um deles, o que significam as mensagens mais comuns e como achar os poucos erros que valem corrigir primeiro.

Como ler um 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 é o recurso, server/main.lua o arquivo dentro dele e 57 a linha.
• O texto depois do número da linha é o erro do Lua. Entre parênteses, o Lua nomeia a variável: local 'Player' significa que uma variável local chamada Player guardava nil.
• As linhas que começam com > são a pilha de chamadas, da mais recente para a mais antiga. Quando a primeira linha aponta para um framework ou uma biblioteca como es_extended ou oxmysql, leia para baixo até a primeira linha de um recurso que você mesmo mantém. Normalmente foi ali que o valor errado nasceu.

Erros comuns e como corrigi-los

attempt to index a nil value

O script lê um campo de algo que não existe. No ESX e no QBCore, quase sempre é o objeto do jogador, buscado para alguém que já saiu ou ainda não terminou de carregar:

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

A verificação na segunda linha é a correção, e o mesmo vale para ESX.GetPlayerFromId(source). Quando a mensagem nomeia um campo, como em (field 'PlayerData'), a tabela acima existe, mas não tem essa chave, o que muitas vezes indica um script escrito para outra versão do framework.

attempt to call a nil value

O script chama uma função que não existe, e o parêntese a nomeia: (field 'GetPlayerData') ou (method 'addMoney'). As causas habituais são uma função que o framework renomeou em uma atualização, um recurso que a define mas inicia depois, ou uma global como ESX que nunca foi definida. O ESX mais novo entrega seu objeto por exports['es_extended']:getSharedObject() ou @es_extended/imports.lua, e um script que ainda espera o evento antigo esx:getSharedObject pode ficar sem ele.

No such export in resource

No such export SendAlert in resource ps-mdt significa que um script chamou exports['ps-mdt']:SendAlert() e ps-mdt não tem um export com esse nome, pelo menos ainda não. Ou o recurso não iniciou, ou roda com outro nome de pasta, ou o export foi renomeado. Coloque o recurso que fornece o export mais acima no server.cfg e confira o nome no fxmanifest.lua dele ou na documentação.

attempt to perform arithmetic on a nil value

Algo como count + 1 em que count é nil, em geral um valor lido do banco de dados ou uma chave de config que não existe. Dê a ele um valor padrão onde é lido: local count = row.count or 0.

attempt to compare number with nil

A mesma causa em uma comparação: if amount > Config.Limit com Limit faltando na sua config. Confira se toda chave que o script lê existe na sua cópia do config.lua, principalmente depois de uma atualização que adicionou chaves novas.

Erros de recursos em JavaScript

Recursos em JavaScript imprimem SCRIPT ERROR: seguido de um erro de JavaScript e de uma pilha com at. TypeError: Cannot read properties of undefined (reading 'citizenid') é a versão em JavaScript de indexar nil, e pede a mesma verificação.

Error running system event handling function

Essa linha significa que um handler de um evento embutido, como playerDropped ou onResourceStart, lançou um erro. As linhas abaixo nomeiam o arquivo e a linha, como em um SCRIPT ERROR normal.

Quais erros corrigir primeiro

Um console com quinhentos erros costuma conter vinte diferentes. Corrija por impacto: primeiro o erro que atingiu mais jogadores, depois tudo que é novo desde a última reinicialização, que em geral é a atualização que você acabou de publicar. Com o console salvo em um arquivo, este comando conta os erros por local:

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

Ele só conta linhas, então um único jogador preso em um loop pode levar um erro inofensivo ao topo, e um erro barulhento de ontem parece igual a um que começou há uma hora.

Deixe o FiveDock agrupá-los

O agente do FiveDock lê o console do servidor conforme ele imprime. Ele junta cada SCRIPT ERROR à sua pilha, mascara nomes de jogadores, endereços IP e identificadores, e agrupa os erros por recurso, arquivo, linha e mensagem, ignorando os números da mensagem para que o mesmo bug conte uma vez só.

No Metro, o Error Hunter lista esses grupos com uma contagem, o número de jogadores atingidos e quando cada um foi visto pela primeira e pela última vez, com o que é novo desde a reinicialização no topo. O Deploy Guard faz um backup antes de uma reinicialização, dá um veredito dez minutos depois e nomeia o recurso por trás de qualquer problema novo.

Perguntas frequentes

O que significa attempt to index a nil value no FiveM?

O script tentou ler um campo de uma variável que é nil, e o nome entre parênteses diz qual. No ESX e no QBCore, costuma ser um objeto de jogador buscado para alguém que desconectou ou ainda não carregou, e a correção é verificar se o objeto existe antes de usá-lo.

Como descubro qual recurso causa um SCRIPT ERROR?

O recurso é o nome depois de @ no início do local, como em @qb-garages/server/main.lua:57. Se for um framework ou uma biblioteca, leia as linhas da pilha que começam com > até chegar à primeira de um recurso que você mesmo mantém.

Por que aparecem SCRIPT ERRORs depois de atualizar um recurso?

Atualizações renomeiam funções e exports, adicionam chaves de config e esperam versões mais novas do framework. Compare o novo config.lua com o seu, procure no changelog por exports renomeados e reinicie os recursos que dependem do que você atualizou.

Posso esconder os SCRIPT ERRORs do console?

Você pode envolver as chamadas em pcall, mas isso esconde o bug e deixa de pé o que ele quebrou. Corrija o valor nil onde ele nasce e agrupe os erros para ver quais importam.