The debug Library
Inspect stack traces, locals, and upvalues with the debug library.
The debug Library is a free Lua Academy lesson on CoddyKit — lesson 4 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the Lua Academy learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.
What Is the debug Library?
The debug library gives low-level access to Lua internals: stack frames, locals, upvalues, hooks, and coroutine state. Use it for debugging, not production logic.
debug.traceback
debug.traceback(msg, level) returns a string with the call stack. Commonly passed to xpcall as the error handler.
local ok, err = xpcall(function()
error("something went wrong")
end, debug.traceback)
print(err)debug.getinfo
debug.getinfo(fn, what) returns a table with info about a function: name, source, line defined, etc.
local function foo() end
local info = debug.getinfo(foo, "Sl")
print(info.source, info.linedefined)Stack Level Inspection
Pass an integer to debug.getinfo to inspect a specific stack frame. Level 1 is the current function, 2 is the caller.
local function where()
local info = debug.getinfo(2, "Sl")
return info.short_src .. ":" .. info.currentline
end
print(where())debug.getlocal and debug.setlocal
debug.getlocal(level, n) returns the name and value of the nth local in a stack frame.
local function example()
local x = 42
print(debug.getlocal(1, 1)) -- x 42
end
example()debug.getupvalue and debug.setupvalue
Inspect and modify upvalues of a function. getupvalue(fn, n) returns name and value.
local x = 10
local function f() return x end
print(debug.getupvalue(f, 1)) -- x 10
debug.setupvalue(f, 1, 99)
print(f()) -- 99debug.sethook
debug.sethook(fn, mask, count) sets a hook called on events: "c" (call), "r" (return), "l" (line), or every N instructions.
local calls = 0
debug.sethook(function() calls = calls + 1 end, "c")
-- ... run some code ...
debug.sethook() -- remove hook
print("calls:", calls)debug.getmetatable
debug.getmetatable(obj) retrieves the metatable even when getmetatable is blocked by a __metatable field.
debug.upvalueid and upvaluejoin
debug.upvalueid(fn, n) returns a unique identifier for an upvalue. debug.upvaluejoin(f1,n1,f2,n2) makes them share a cell.
Caution: debug Library Risks
The debug library can violate encapsulation and break invariants. Never use it in production code. Reserve for testing, profiling, and development tools.
debug.traceback in xpcall
The most common production-safe use of debug is passing debug.traceback as the error handler to xpcall for rich error messages.
debug Library Question
Which debug function is safe and commonly used in production error handling?
Recap: debug Library
The debug library exposes stack frames, locals, upvalues, and hooks. Use debug.traceback with xpcall for rich errors; treat the rest as developer-only introspection tools.
Frequently asked questions
Is the “The debug Library” lesson free?
Yes — the full text of “The debug Library” is free to read here on the web, and the Lua Academy course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the Lua Academy course, upgrade to CoddyKit PRO.
What will I learn in “The debug Library”?
Inspect stack traces, locals, and upvalues with the debug library. You practise Lua Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.
Do I need any experience to start Lua Academy?
No prior experience is required. Lua Academy on CoddyKit is structured for beginners through advanced learners; this is — lesson 4 of 4, so you can start here or from the beginning and move at your own pace.
How long does the “The debug Library” lesson take?
Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.
Can I write and run code in this Lua Academy lesson?
Yes. Every Lua Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.
All lessons in this course
- math Library Functions
- table Library Functions
- os and io Libraries
- The debug Library