Error Handling in Lua (pcall/error)

Lua does not have try/catch; instead, the built-in error(message, level) function raises an error that immediately unwinds the call stack until something catches it. The message is usually a string but can be any Lua value (including a table, useful for structured error objects). The optional level argument controls whether position information (file:line) is prepended: level 1 (the default) points to where error() was called, level 2 points to the caller of the function that called error(), and level 0 suppresses position info entirely.

pcall(f, ...) ("protected call") invokes function f with the given arguments inside a protected environment. It always returns at least a boolean: true plus f's normal return values if f completed without error, or false plus the error value if f raised one. This is the fundamental Lua idiom for "catching" errors — instead of a try/catch block, you wrap the risky call itself in pcall and branch on its first return value.

xpcall(f, handler, ...) works like pcall but takes an additional error handler function that runs while the stack is still unwinding, before the stack is fully discarded. This matters because it lets you call debug.traceback() inside the handler to capture a full stack trace, something you cannot reconstruct after pcall has already returned and the original call stack is gone. xpcall is the standard choice when you need detailed diagnostics (e.g. logging) rather than just a pass/fail result.

Because error() accepts any Lua value, libraries sometimes raise a table like error({code = 404, message = "not found"}) so calling code can programmatically inspect err.code after a pcall rather than pattern-matching a string. Separately, assert(v, message) is a shorthand that raises error(message) if v is false or nil, and otherwise returns all its arguments unchanged — it's commonly used to validate function arguments or the success of an I/O operation like assert(io.open("data.txt")), which raises immediately if the file couldn't be opened.