Como ler um FiveM SCRIPT ERROR: arquivo, linha e stack trace

Um erro típico no console:

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:...)

Parece ruído, mas cada parte tem um significado, e geralmente te diz exatamente onde olhar. Este guia mostra como lê-lo, onde encontrá-lo, e o que fazer quando não é suficiente.

#A primeira linha: o quê, onde e por quê

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

• SCRIPT ERROR: marca um erro Lua em um script. O script continua rodando após, mas o código que falhou parou naquela linha.
• @my_script/server/main.lua é o nome do recurso (my_script) e o caminho do arquivo dentro da pasta de recurso.
• :42 é o número da linha naquele arquivo.
• O resto é a mensagem: attempt to index a nil value (local 'xPlayer'). Lua lê assim: na linha 42 você tentou usar algo dentro de xPlayer, mas xPlayer é nil.

Abra o arquivo, vá para aquela linha, e olhe as variáveis que aquela linha usa. Na maioria dos casos a resposta já está lá. Mensagens comuns têm seus próprios guias: attempt to call a nil value e attempt to compare nil.

#O stack trace: como o código chegou lá

As linhas começando com > são o stack trace. Lista as funções que estavam rodando, da que falhou para baixo até a que iniciou:

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

A primeira linha após o erro é o mesmo lugar que o erro. Linhas abaixo mostram quem chamou aquela função. Quando o erro está dentro de uma biblioteca ou outro recurso, uma linha do seu próprio script mais abaixo na lista é frequentemente a causa real, porque seu script passou um valor errado para ela.

Linhas que começam com citizen:/scripting/lua/... (por exemplo citizen:/scripting/lua/scheduler.lua) pertencem ao próprio FiveM. São parte da maquinaria que roda seus eventos e threads. Você pode ignorá-las: o erro nunca é consertado lá, e apenas mostram que uma thread ou evento estava rodando.

#Cliente ou server: onde olhar

Um erro de script aparece no lado onde o código roda:

• Client scripts (client_scripts, arquivos em uma pasta client): pressione F8 no jogo para abrir o console do cliente. Se você não vê nada, role para cima, pois erros podem rolar rápido.
• Server scripts (server_scripts, arquivos em uma pasta server): leia o console do server. Em txAdmin, é a página Live Console. Em um server iniciado de um terminal, é aquela janela de terminal.
• Shared scripts rodam em ambos os lados, então o erro pode aparecer em qualquer lugar.

Dica: se um menu ou uma ação não faz nada e F8 está vazio, verifique o console do server. O código que falha pode estar no lado do server.

#Qual linha olhar

1. Leia a mensagem primeiro: diz qual tipo de problema é (nil, um tipo errado, um export faltando).
2. Abra o arquivo e linha da primeira linha. Verifique cada variável nele.
3. Se o arquivo pertence a uma biblioteca (ox_lib, o framework), desça o stack trace até alcançar uma linha do script que você está consertando.
4. Verifique se o erro aparece uma vez ou constantemente. Um erro constante em um loop inunda o console. Conserte aquele primeiro, pois esconde outras mensagens.

Erros com o texto No such export ou could not find dependency são diferentes. São sobre recursos, não linhas de código. Veja could not find dependency.

#Quando a linha não é suficiente: adicione prints

Se a linha usa várias variáveis e você não sabe qual é nil, imprima-as logo antes:

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

Rode o código novamente e leia o console. Algumas dicas para prints úteis:

• Imprima o tipo bem como o valor: type(value) mostra nil, number, string, table ou function.
• Use json.encode(table) para ver dentro de uma tabela. Um simples print(table) apenas mostra um endereço de memória.
• Coloque um rótulo curto na frente, então você pode encontrar a linha em um console ocupado.
• Imprima no início de uma função, para confirmar que roda absolutamente.

Remova os prints uma vez o problema seja consertado, pois custam performance em loops ocupados.

#Onde um erro não aparece

• Escrowed scripts escondem seu código. O erro te dá um nome de arquivo, mas o arquivo é encriptado e você não pode ler a linha. Contate o autor com o texto de erro completo.
• NUI errors (o menu em si, escrito em HTML e JavaScript) não aparecem em F8 como SCRIPT ERROR. Abra as ferramentas de desenvolvedor NUI para lê-las: o comando nui_devtools no console F8 os abre em uma aba do navegador.
• Erros nos primeiros segundos: quando você inicia o server, erros de recursos que falham ao carregar podem passar rápido. Procure no console ou role para cima, ou reinicie apenas aquele recurso e observe.

#O que enviar quando você pedir ajuda

Copie o erro completo, o stack trace incluído, como texto, e diga se vem de F8 ou do console do server. Adicione a linha de código que aponta e o framework que você usa. Uma screenshot de uma linha recortada não é suficiente para ninguém ajudá-lo.

#Checklist