Lua Academy · Aula

A função error()

Gere erros com error() e compreenda os níveis e as mensagens de erro.

A função error() é uma aula grátis de Lua Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Lua Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Lua Academy inclui 4 aulas no total.

Gerando Erros

error(message, level) gera um erro Lua. A execução é interrompida e o erro se propaga pela pilha de chamadas até ser capturado por pcall ou xpcall, ou até encerrar o programa. A mensagem pode ser qualquer valor — string, tabela ou número.

local function divide(a, b)
  if b == 0 then
    error("division by zero")
  end
  return a / b
end

print(divide(10, 2))    -- 5.0
-- divide(10, 0)        -- ERROR: division by zero

Níveis de Erro

O segundo argumento de error() controla onde o erro é indicado. O nível 1 (padrão) aponta para a própria chamada de error(). O nível 2 aponta para quem fez a chamada. O nível 0 não adiciona informações de posição. Use o nível 2 em funções de biblioteca para atribuir a responsabilidade ao código do usuário.

local function assertPositive(n, name)
  if n <= 0 then
    error((name or "value") .. " must be positive, got " .. n, 2)
    -- level 2: blame the caller, not this function
  end
  return n
end

local function compute(x)
  assertPositive(x, "x")   -- error points here if x <= 0
  return math.sqrt(x)
end

compute(-5)  -- error: "x must be positive, got -5" at compute() call

Erro com Objetos de Tabela

Passar uma tabela como valor do erro permite que quem fez a chamada examine informações estruturadas sobre o erro: código, mensagem e contexto. Isso é mais informativo do que uma string simples e permite o tratamento programático de erros.

local function openDB(host, port)
  if port < 1 or port > 65535 then
    error({code="INVALID_PORT", port=port,
           msg="port out of range: " .. port})
  end
  -- ... connect
  return {host=host, port=port}
end

local ok, err = pcall(openDB, "localhost", -1)
if not ok and type(err) == "table" then
  print("Code:", err.code)    -- INVALID_PORT
  print("Port:", err.port)    -- -1
  print("Msg:", err.msg)
end

assert() como Forma Abreviada

assert(v, msg) é equivalente a if not v then error(msg, 2) end; return v, .... É uma forma idiomática de verificar pré-condições. Se v for avaliado como verdadeiro, assert retornará todos os seus argumentos (o que é útil para encadeamento).

local function sqrt(n)
  assert(type(n) == "number", "expected number, got " .. type(n))
  assert(n >= 0, "sqrt of negative: " .. n)
  return math.sqrt(n)
end

print(sqrt(16))    -- 4.0
print(sqrt(2))     -- 1.4142...
-- sqrt("hi")      -- ERROR: expected number, got string

error() versus return nil,err

Há duas convenções para sinalizar falhas: error() (estilo de exceção) ou return nil, msg (estilo funcional). Use error() para condições realmente inesperadas (erros de programação, violações de contrato). Use nil, msg para falhas esperadas (arquivo não encontrado, tempo limite da rede).

-- Exception style (programming error)
local function mustExist(t, key)
  local v = t[key]
  if v == nil then error("required key missing: " .. key, 2) end
  return v
end

-- Functional style (expected failure)
local function findUser(id)
  -- ... database query
  return nil, "user not found"  -- expected: user may not exist
end

Erro em Metamétodos

Erros podem ser gerados dentro de metamétodos. Se um metamétodo gerar um erro, ele se propagará para o código que acionou a operação (como uma expressão aritmética). Sempre proteja os metamétodos contra entradas inválidas.

local SafeDiv = {}
SafeDiv.__index = SafeDiv

SafeDiv.__div = function(a, b)
  if b.value == 0 then
    error("SafeDiv: division by zero", 2)
  end
  return SafeDiv.new(a.value / b.value)
end

function SafeDiv.new(v)
  return setmetatable({value=v}, SafeDiv)
end

local a = SafeDiv.new(10)
local b = SafeDiv.new(0)
local ok, err = pcall(function() return a / b end)
print(ok, err)

Tipos de erro personalizados

Crie um auxiliar para construir objetos de erro tipados. Inclua uma etiqueta de tipo para que os chamadores possam distinguir entre diferentes tipos de erros e tratá-los adequadamente.

local function newError(kind, msg, extra)
  return setmetatable(
    {kind=kind, message=msg, extra=extra},
    {__tostring = function(e)
      return "[" .. e.kind .. "] " .. e.message
    end}
  )
end

local E = {
  notFound = function(name) return newError("NOT_FOUND","not found: "..name) end,
  badInput = function(msg)  return newError("BAD_INPUT", msg) end,
}

local ok, err = pcall(error, E.notFound("config.json"))
if not ok then print(err.kind, err.message) end

Propagação de erros

Quando uma função chama outra que gera um erro, o erro se propaga automaticamente pela pilha. Não é necessário gerá-lo novamente — basta não capturá-lo. Capture os erros somente no nível em que seja possível tratá-los ou relatá-los de maneira significativa.

local function step3() error("step3 failed") end
local function step2() step3() end
local function step1() step2() end

local ok, err = pcall(step1)
if not ok then
  -- err includes the source location
  print("Caught at top level:", err)
end
-- Error: input:1: step3 failed

Rastreamento da pilha com debug.traceback

Um error() simples fornece uma linha de contexto. Para obter um rastreamento completo da pilha, use debug.traceback(msg) como valor do erro. Isso normalmente é feito em um manipulador de xpcall.

local function buggy()
  local t = nil
  return t.field   -- nil indexing: error
end

local ok, err = xpcall(buggy, function(e)
  return debug.traceback(e, 2)  -- full stack trace
end)

if not ok then
  print(err)  -- full traceback
end

Geração de erros novamente

Às vezes, você captura um erro para adicionar contexto e depois o gera novamente. Use error(err, 0) (nível 0) ao gerar novamente um erro de string, para evitar adicionar outro prefixo de localização a uma mensagem que já foi formatada.

local function loadAndParse(path)
  local ok, err = pcall(function()
    local f = io.open(path, "r")
    if not f then error("cannot open: " .. path) end
    local content = f:read("a")
    f:close()
    return content
  end)
  if not ok then
    error("loadAndParse failed: " .. err, 0)  -- re-raise with context
  end
end

local ok2, msg = pcall(loadAndParse, "missing.txt")
print(ok2, msg)

Verificação rápida

O que significa o nível 2 em error("msg", 2)?

Recapitulação: error()

Resumo:

error(msg, level) — gera um erro; o nível 2 responsabiliza o chamador
Use tabelas para erros estruturados com tipo e contexto
assert(v, msg) — verificação idiomática de pré-condições
Use error() para bugs; retorne nil+err para falhas esperadas
Gere novamente com error(err, 0) para preservar o formato da mensagem

Perguntas Frequentes

A aula “A função error()” é grátis?

Sim — o texto completo de “A função error()” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Lua Academy, atualize para CoddyKit PRO. O curso de Lua Academy inclui 4 aulas no total.

O que vou aprender em “A função error()”?

Gere erros com error() e compreenda os níveis e as mensagens de erro. Você pratica Lua Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Lua Academy?

Nenhuma experiência prévia é necessária. Lua Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “A função error()”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Lua Academy?

Sim. Cada aula de Lua Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

← Voltar para Lua Academy