Error Handling in Lua

Intermediate ~25 min read

Robust error handling is crucial for building reliable applications. Lua provides several mechanisms for handling errors: error(), assert(), pcall(), and xpcall(). In this lesson, you'll learn how to handle errors gracefully and build resilient code. Let's explore error handling in Lua!

Raising Errors

Using error()

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

-- This will raise an error
-- divide(10, 0)  -- Error: Division by zero

Error with Level

function validateAge(age)
    if type(age) ~= "number" then
        error("Age must be a number", 2)  -- Level 2: caller's location
    end
    if age < 0 or age > 150 then
        error("Age must be between 0 and 150", 2)
    end
    return true
end

Error Levels:

1 (default): Error at current function
2: Error at caller's location
0: No location information

Using assert()

assert() raises an error if a condition is false:

function sqrt(x)
    assert(x >= 0, "Cannot take square root of negative number")
    return math.sqrt(x)
end

print(sqrt(16))  -- 4
-- print(sqrt(-4))  -- Error: Cannot take square root of negative number

Assert with Function Calls

-- Assert that a file opened successfully
local file = assert(io.open("data.txt", "r"), "Failed to open file")

-- Assert function return values
local function getConfig()
    return nil, "Configuration not found"
end

local config = assert(getConfig())  -- Error: Configuration not found

-- Error Handling Basics in Lua

-- Lua provides several ways to handle errors

-- 1. error() function
-- Raises an error and stops execution
print("=== error() function ===")

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

print("10 / 2 =", divide(10, 2))
-- print(divide(10, 0))  -- Would stop execution with error

-- 2. error() with level parameter
-- Level controls where error is reported from
local function validateAge(age)
    if type(age) ~= "number" then
        error("Age must be a number", 2)  -- Report error at caller
    end
    if age < 0 or age > 150 then
        error("Age must be between 0 and 150", 2)
    end
    return true
end

local function createPerson(name, age)
    validateAge(age)  -- Error will be reported here
    return {name = name, age = age}
end

-- 3. assert() function
-- Raises error if condition is false
print("\n=== assert() function ===")

local function sqrt(x)
    assert(x >= 0, "Cannot take square root of negative number")
    return math.sqrt(x)
end

print("sqrt(16) =", sqrt(16))
-- print(sqrt(-4))  -- Would error

-- assert with multiple return values
local function openFile(filename)
    local file, err = io.open(filename, "r")
    assert(file, "Could not open file: " .. (err or "unknown error"))
    return file
end

-- 4. Custom error messages
print("\n=== Custom Error Messages ===")

local function withdraw(balance, amount)
    if amount <= 0 then
        error("Amount must be positive")
    end
    if amount > balance then
        error(string.format(
            "Insufficient funds: balance=%.2f, requested=%.2f",
            balance, amount
        ))
    end
    return balance - amount
end

local balance = 100
balance = withdraw(balance, 30)
print("New balance:", balance)

-- 5. Error objects
-- Errors can be any Lua value, not just strings
print("\n=== Error Objects ===")

local function processData(data)
    if type(data) ~= "table" then
        error({
            code = "INVALID_TYPE",
            message = "Data must be a table",
            expected = "table",
            got = type(data)
        })
    end
    return data
end

-- 6. Stack traces
-- error() includes stack trace information
print("\n=== Stack Traces ===")

local function level3()
    error("Error at level 3")
end

local function level2()
    level3()
end

local function level1()
    level2()
end

-- level1()  -- Would show stack trace

-- 7. Validation patterns
print("\n=== Validation Patterns ===")

local function validateEmail(email)
    if type(email) ~= "string" then
        return false, "Email must be a string"
    end
    if not email:match("@") then
        return false, "Email must contain @"
    end
    return true
end

local valid, err = validateEmail("test@example.com")
if valid then
    print("Email is valid")
else
    print("Invalid email:", err)
end

-- 8. Error handling in constructors
print("\n=== Constructor Validation ===")

local Person = {}
Person.__index = Person

function Person.new(name, age)
    if type(name) ~= "string" or #name == 0 then
        error("Name must be a non-empty string")
    end
    if type(age) ~= "number" or age < 0 then
        error("Age must be a positive number")
    end
    
    local self = setmetatable({}, Person)
    self.name = name
    self.age = age
    return self
end

local person = Person.new("Alice", 25)
print("Created person:", person.name)

-- 9. Graceful degradation
print("\n=== Graceful Degradation ===")

local function safeOperation(x)
    if type(x) ~= "number" then
        return nil, "Input must be a number"
    end
    if x < 0 then
        return nil, "Input must be non-negative"
    end
    return math.sqrt(x)
end

local result, err = safeOperation(16)
if result then
    print("Result:", result)
else
    print("Error:", err)
end

-- 10. Error messages best practices
print("\n=== Best Practices ===")

local function betterError(condition, message, context)
    if not condition then
        local fullMessage = message
        if context then
            fullMessage = fullMessage .. " (context: " .. tostring(context) .. ")"
        end
        error(fullMessage, 2)
    end
end

local function processOrder(order)
    betterError(type(order) == "table", "Order must be a table", type(order))
    betterError(order.id, "Order must have an ID", "missing field: id")
    betterError(order.amount > 0, "Order amount must be positive", order.amount)
    print("Processing order:", order.id)
end

processOrder({id = 123, amount = 99.99})

Output

Click Run to execute your code

Protected Calls with pcall()

pcall() (protected call) catches errors without stopping execution:

function riskyFunction()
    error("Something went wrong!")
end

local success, result = pcall(riskyFunction)

if success then
    print("Success:", result)
else
    print("Error:", result)  -- Error: Something went wrong!
end

pcall() with Arguments

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

local success, result = pcall(divide, 10, 2)
print(success, result)  -- true  5

local success, error = pcall(divide, 10, 0)
print(success, error)  -- false  Division by zero

Practical pcall() Usage

local function safeRequire(module)
    local success, result = pcall(require, module)
    if success then
        return result
    else
        print("Warning: Failed to load module " .. module)
        return nil
    end
end

local json = safeRequire("json")
if json then
    -- Use json module
end

-- Protected Calls with pcall() in Lua

-- pcall() (protected call) catches errors without stopping execution
-- Returns: success (boolean), result or error message

print("=== Basic pcall() Usage ===")

local function riskyFunction(x)
    if x < 0 then
        error("Negative number not allowed!")
    end
    return math.sqrt(x)
end

-- Without pcall - would crash
-- local result = riskyFunction(-4)

-- With pcall - catches error
local success, result = pcall(riskyFunction, 16)
if success then
    print("Result:", result)
else
    print("Error caught:", result)
end

local success2, result2 = pcall(riskyFunction, -4)
if success2 then
    print("Result:", result2)
else
    print("Error caught:", result2)
end

-- pcall with multiple arguments
print("\n=== pcall() with Multiple Arguments ===")

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

local ok, result = pcall(divide, 10, 2)
print("10 / 2:", ok, result)

local ok2, result2 = pcall(divide, 10, 0)
print("10 / 0:", ok2, result2)

-- pcall with anonymous functions
print("\n=== pcall() with Anonymous Functions ===")

local ok, result = pcall(function()
    local x = 10
    local y = 0
    if y == 0 then
        error("Cannot divide by zero")
    end
    return x / y
end)

if not ok then
    print("Error:", result)
end

-- pcall for file operations
print("\n=== pcall() for File Operations ===")

local function readFile(filename)
    local file = io.open(filename, "r")
    if not file then
        error("File not found: " .. filename)
    end
    local content = file:read("*all")
    file:close()
    return content
end

local ok, content = pcall(readFile, "nonexistent.txt")
if ok then
    print("File content:", content)
else
    print("Could not read file:", content)
end

-- pcall for JSON parsing (simulated)
print("\n=== pcall() for Parsing ===")

local function parseJSON(str)
    if str == "" then
        error("Empty JSON string")
    end
    if not str:match("^%s*{") then
        error("Invalid JSON format")
    end
    -- Simulated parsing
    return {parsed = true}
end

local ok, data = pcall(parseJSON, '{"name": "Alice"}')
if ok then
    print("Parsed successfully")
else
    print("Parse error:", data)
end

-- pcall in a loop
print("\n=== pcall() in Loop ===")

local operations = {
    function() return 10 / 2 end,
    function() return 10 / 0 end,  -- Error
    function() return 10 / 5 end,
    function() error("Custom error") end
}

for i, op in ipairs(operations) do
    local ok, result = pcall(op)
    if ok then
        print(i .. ". Success:", result)
    else
        print(i .. ". Failed:", result)
    end
end

-- pcall with module loading
print("\n=== pcall() with require() ===")

local function loadModule(name)
    local ok, module = pcall(require, name)
    if ok then
        print("Loaded module:", name)
        return module
    else
        print("Failed to load:", name)
        return nil
    end
end

local math = loadModule("math")
local fake = loadModule("nonexistent_module")

-- pcall for validation
print("\n=== pcall() for Validation ===")

local function validateUser(user)
    assert(type(user) == "table", "User must be a table")
    assert(user.name, "User must have a name")
    assert(user.age and user.age > 0, "User must have valid age")
    return true
end

local users = {
    {name = "Alice", age = 25},
    {name = "Bob"},  -- Missing age
    "invalid",  -- Not a table
}

for i, user in ipairs(users) do
    local ok, err = pcall(validateUser, user)
    if ok then
        print(i .. ". Valid user")
    else
        print(i .. ". Invalid:", err)
    end
end

-- pcall with cleanup
print("\n=== pcall() with Cleanup ===")

local function processWithCleanup()
    local resource = {open = true}
    
    local ok, result = pcall(function()
        -- Simulated processing
        if math.random() > 0.5 then
            error("Random error")
        end
        return "Success"
    end)
    
    -- Cleanup always happens
    resource.open = false
    print("Resource cleaned up")
    
    if ok then
        return result
    else
        return nil, result
    end
end

-- Retry pattern with pcall
print("\n=== Retry Pattern ===")

local function retryOperation(func, maxAttempts)
    for attempt = 1, maxAttempts do
        local ok, result = pcall(func)
        if ok then
            print("Success on attempt", attempt)
            return result
        else
            print("Attempt", attempt, "failed:", result)
            if attempt < maxAttempts then
                print("Retrying...")
            end
        end
    end
    return nil, "All attempts failed"
end

local attempts = 0
local result = retryOperation(function()
    attempts = attempts + 1
    if attempts < 3 then
        error("Not ready yet")
    end
    return "Finally worked!"
end, 5)

print("Final result:", result)

-- pcall vs direct call
print("\n=== pcall() vs Direct Call ===")

local function safeCall(func, ...)
    local ok, result = pcall(func, ...)
    if ok then
        return result
    else
        print("Error handled:", result)
        return nil
    end
end

local result1 = safeCall(math.sqrt, 16)
print("Safe sqrt(16):", result1)

local result2 = safeCall(function(x)
    if x < 0 then error("Negative!") end
    return math.sqrt(x)
end, -4)
print("Safe sqrt(-4):", result2)

Output

Click Run to execute your code

xpcall() with Error Handler

xpcall() allows you to specify a custom error handler:

local function errorHandler(err)
    return "Error occurred: " .. tostring(err) .. "\n" .. debug.traceback()
end

local function riskyFunction()
    local x = nil
    return x.field  -- Error: attempt to index nil value
end

local success, result = xpcall(riskyFunction, errorHandler)

if not success then
    print(result)  -- Prints error with stack trace
end

Custom Error Handler

local function detailedErrorHandler(err)
    local info = {
        error = tostring(err),
        timestamp = os.date("%Y-%m-%d %H:%M:%S"),
        traceback = debug.traceback()
    }
    return info
end

local function buggyFunction()
    error("Oops!")
end

local success, errorInfo = xpcall(buggyFunction, detailedErrorHandler)

if not success then
    print("Error:", errorInfo.error)
    print("Time:", errorInfo.timestamp)
    print("Trace:", errorInfo.traceback)
end

-- Extended Protected Calls with xpcall() in Lua

-- xpcall() is like pcall() but allows custom error handlers
-- Returns: success (boolean), result or error handler result

print("=== Basic xpcall() Usage ===")

-- Error handler function
local function errorHandler(err)
    return "Error caught: " .. tostring(err)
end

local function riskyFunction(x)
    if x < 0 then
        error("Negative number!")
    end
    return math.sqrt(x)
end

local ok, result = xpcall(function() return riskyFunction(16) end, errorHandler)
print("Success:", ok, "Result:", result)

local ok2, result2 = xpcall(function() return riskyFunction(-4) end, errorHandler)
print("Success:", ok2, "Result:", result2)

-- Error handler with stack trace
print("\n=== Error Handler with Stack Trace ===")

local function detailedErrorHandler(err)
    local trace = debug.traceback(err, 2)
    return trace
end

local function level3()
    error("Error at level 3")
end

local function level2()
    level3()
end

local function level1()
    level2()
end

local ok, result = xpcall(level1, detailedErrorHandler)
if not ok then
    print("Error with trace:")
    print(result)
end

-- Custom error handler with logging
print("\n=== Error Handler with Logging ===")

local errorLog = {}

local function loggingErrorHandler(err)
    local entry = {
        error = tostring(err),
        time = os.time(),
        trace = debug.traceback()
    }
    table.insert(errorLog, entry)
    return "Error logged: " .. tostring(err)
end

local function faultyOperation()
    error("Something went wrong")
end

xpcall(faultyOperation, loggingErrorHandler)
print("Errors logged:", #errorLog)

-- Error handler with context
print("\n=== Error Handler with Context ===")

local function contextErrorHandler(context)
    return function(err)
        return string.format("[%s] %s", context, tostring(err))
    end
end

local ok, result = xpcall(
    function() error("Database error") end,
    contextErrorHandler("DATABASE")
)
print(result)

local ok2, result2 = xpcall(
    function() error("Network error") end,
    contextErrorHandler("NETWORK")
)
print(result2)

-- Error recovery with xpcall
print("\n=== Error Recovery ===")

local function recoveryHandler(err)
    print("Attempting recovery from:", err)
    return "default_value"  -- Fallback value
end

local function unreliableOperation()
    if math.random() > 0.5 then
        error("Random failure")
    end
    return "success"
end

local ok, result = xpcall(unreliableOperation, recoveryHandler)
print("Result:", result)

-- Error handler with cleanup
print("\n=== Error Handler with Cleanup ===")

local resources = {}

local function cleanupErrorHandler(err)
    print("Cleaning up resources...")
    for i, resource in ipairs(resources) do
        if resource.open then
            resource.open = false
            print("Closed resource", i)
        end
    end
    return "Error after cleanup: " .. tostring(err)
end

local function operationWithResources()
    table.insert(resources, {open = true})
    table.insert(resources, {open = true})
    error("Operation failed")
end

xpcall(operationWithResources, cleanupErrorHandler)

-- Nested xpcall
print("\n=== Nested xpcall ===")

local function innerErrorHandler(err)
    return "Inner handler: " .. tostring(err)
end

local function outerErrorHandler(err)
    return "Outer handler: " .. tostring(err)
end

local ok, result = xpcall(function()
    return xpcall(function()
        error("Inner error")
    end, innerErrorHandler)
end, outerErrorHandler)

print("Nested result:", result)

-- Error handler with retry logic
print("\n=== Error Handler with Retry ===")

local retryCount = 0
local maxRetries = 3

local function retryErrorHandler(err)
    retryCount = retryCount + 1
    if retryCount < maxRetries then
        print("Retry", retryCount, "after error:", err)
        return "retry"
    else
        return "Max retries reached: " .. tostring(err)
    end
end

local function unreliableTask()
    if retryCount < 2 then
        error("Not ready yet")
    end
    return "Success!"
end

local result
repeat
    local ok, res = xpcall(unreliableTask, retryErrorHandler)
    if ok then
        result = res
        break
    end
until retryCount >= maxRetries

print("Final result:", result)

-- Error handler with notification
print("\n=== Error Handler with Notification ===")

local notifications = {}

local function notifyErrorHandler(err)
    local notification = {
        type = "error",
        message = tostring(err),
        timestamp = os.date("%Y-%m-%d %H:%M:%S")
    }
    table.insert(notifications, notification)
    print("Notification sent:", notification.message)
    return err
end

xpcall(function()
    error("Critical error occurred")
end, notifyErrorHandler)

print("Total notifications:", #notifications)

-- Comparing pcall and xpcall
print("\n=== pcall vs xpcall ===")

local function testFunction()
    error("Test error")
end

-- pcall - simple error message
local ok1, err1 = pcall(testFunction)
print("pcall error:", err1)

-- xpcall - enhanced error message
local ok2, err2 = xpcall(testFunction, function(err)
    return "Enhanced: " .. tostring(err) .. " [at " .. os.time() .. "]"
end)
print("xpcall error:", err2)

-- Error handler for debugging
print("\n=== Debugging Error Handler ===")

local function debugErrorHandler(err)
    print("=== Error Debug Info ===")
    print("Error:", err)
    print("Stack trace:")
    print(debug.traceback())
    print("======================")
    return err
end

xpcall(function()
    local function deepFunction()
        error("Deep error")
    end
    deepFunction()
end, debugErrorHandler)

-- Production vs Development error handlers
print("\n=== Environment-Specific Handlers ===")

local isDevelopment = true

local function getErrorHandler()
    if isDevelopment then
        return function(err)
            return debug.traceback(err, 2)
        end
    else
        return function(err)
            return "An error occurred. Please contact support."
        end
    end
end

xpcall(function()
    error("Something failed")
end, getErrorHandler())

Output

Click Run to execute your code

Error Handling Patterns

Return nil, error Pattern

local function readFile(filename)
    local file, err = io.open(filename, "r")
    if not file then
        return nil, "Failed to open file: " .. err
    end
    
    local content = file:read("*all")
    file:close()
    
    return content
end

local content, err = readFile("data.txt")
if not content then
    print("Error:", err)
else
    print("Content:", content)
end

Try-Catch Pattern

local function try(func, catch)
    local success, result = pcall(func)
    if not success then
        if catch then
            catch(result)
        end
        return nil
    end
    return result
end

-- Usage
try(function()
    error("Something went wrong")
end, function(err)
    print("Caught error:", err)
end)

Retry Pattern

local function retry(func, maxAttempts, delay)
    local attempts = 0
    
    while attempts < maxAttempts do
        attempts = attempts + 1
        local success, result = pcall(func)
        
        if success then
            return result
        end
        
        if attempts < maxAttempts then
            print("Attempt " .. attempts .. " failed, retrying...")
            -- In real code, you'd sleep here
        end
    end
    
    error("Failed after " .. maxAttempts .. " attempts")
end

-- Usage
local result = retry(function()
    -- Potentially failing operation
    if math.random() > 0.7 then
        return "Success!"
    else
        error("Random failure")
    end
end, 3)