Assim como em toda linguagem, erros são consequências comuns quando estamos programando. Na linguagem Lua, podemos tratar erros utilizando as funções assert, error, pcall, xcall e também rastrear erros com o traceback .

Com a função assert, podemos passar como argumentos expressões para serem validadas. Se o retorno for false, uma mensagem de erro será exibida e a execução do programa será interrompida imediatamente, sem que seja possível uma recuperação.

Sintaxe

assert(condicao,<mensagem_erro>)

Exemplo 1

function funcao1(param)
  assert(type(a) == "string","parâmetro inválido.")
  print(param)
end
--passando parâmetro incorreto
funcao1(1)

Saída

lua5.3: Main.lua:2: parâmetro inválido.
stack traceback:
	[C]: in function 'assert'
	Main.lua:2: in function 'funcao1'
	Main.lua:7: in main chunk
	[C]: in ?

A função error tem a finalidade de encerrar nossos exibindo uma mensagem, que é passada como argumentos. Diferente da função assert, error não possui uma condição como argumento para validação. Com a função error, será abortado.

Sintaxe

error(message,[,<level>])

Onde

message: mensagem de erro que desejamos exibir
&llevel>: Nível de chamada em que mensagem em ocorreu o erro. Opcional

Exemplo 2

function funcao1(param)
  error("erro desconhecido. O programa será abortado")
  print(param)
end
--passando parâmetro incorreto
funcao1(1)

Saída

lua5.3: erro desconhecido. O programa será abortado
stack traceback:
	[C]: in function 'error'
	Main.lua:4: in function 'funcao1'
	Main.lua:10: in main chunk
	[C]: in ?

Na linguagem Lua existe a possibilidade de executarmos uma função e verificar se ocorreu um erro ou não. Assim, de acordo com um retorno de um status retornado, podemos fazer os devidos tratamentos. Essa possibilidade é obtida utilizando a função pcall e xpcall.

Sintaxe

status, valor_retorno = pcall(<f>, arg1,..., argN)

Retorno

<f>: função para executar
arg1..argN: argumentos e <f>
status: true se não houver erro, false caso contrário.
valor_retorno: mensagem de erro ou valor retornado pela função

Exemplo 3

function funcao1(param)
  if(type(param) ~= "string") then
    error("funcao1: param com tipagem incorreta.")
  end
  return 10
end
--passando argumento errado
local status,retorno = pcall(funcao1,1)

if status == false then --houve erro
  print(retorno) 
else                    --não houve erro
  print("OK. Executou sem erro")
end

Saída

Main.lua:3: funcao1: param com tipagem incorreta

Com a função xpcall, temos a possibilidade de também passar uma função, para ser executada/testada como argumento. Além disso, podemos passar uma segunda função para lidar com erros caso estes ocorram.

Sintaxe

status,valor_retorno = xpcall(<f>, <err>,arg1,..., argN)

Sintaxe

function = nome_funcao_err(error)

Onde

<f>: função para executar
<err>: função para tratamento do erro
error: erro ocorrido
arg1..argN: argumentos e <f>
status: true se não houver erro, false caso contrário.
valor_retorno: valor retornado pela função

Exemplo 3

function funcao1(param)
  if(type(param) ~= "string") then
    error("funcao1: param com tipagem incorreta.")
  end
  return 10
end

function funcao_erro(err) 
  print(err)
end
--passando argumento errado
local status,erro,retorno = pcall(funcao1,funcao_erro,1)

--imprimindo retornos
print(status) 
print(erro)
print(retorno)

Saída

false
Main.lua:3: funcao1: param com tipagem incorreta.
nil

O traceback é o local onde ficam armazenadas a pilha de chamadas das funções durante a execução de nossos programas. Quando um erro ocorre, o traceback pode ser exibido pelo interpretador de Lua.

Exemplo 4

function funcao1()
  funcao2()
end

function funcao2()
  funcao3()
end

function funcao3()
  print(a/0)
end
--recuperando função
funcao1()

Saída

lua5.3: Main.lua:10: attempt to perform arithmetic on a nil value (global 'a')
stack traceback:
	Main.lua:10: in function 'funcao3'
	Main.lua:6: in function 'funcao2'
	Main.lua:2: in function 'funcao1'
	Main.lua:13: in main chunk
	[C]: in ?

Para analisarmos a origem do erro, devemos analisar o backtrace iniciando na última linha até a primeira, pois a pilha de execuções é armazenada da forma LIFO(Last In, Firt Out).

Sintaxe

nome_modulo: numero_linha in descricao_chamada

Onde

nome_modulo: módulo inicial
numero_linha: número da linha da chamada de uma função 
descricao_chamada: descrição do erro ou chamada a uma função

No exemplo abaixo mostra o backtrace do exemplo 4 está ordem invertida as chamadas para exemplificar a ordem da leitura.

Exemplo 5

[C]: in ?
Main.lua:13: in main chunk
Main.lua:2: in function 'funcao1'
Main.lua:6: in function 'funcao2'
Main.lua:10: in function 'funcao3'
lua5.3: Main.lua:10: attempt to perform arithmetic on a nil value (global 'a')

1. 15/09/2025 - revisão 4 - Ajustes: pontuais, sintaxes e objetivos
2. 12/09/2024 - revisão 3 - Ajuste gramatical em introdução, xpcall
3. 30/08/2024 - revisão 2 - Correção em links de objetivos
4. 03/10/2023 - revisão 1 - Correção em referências e erros gramaticais
5. 26/05/2023 - versão inicial