Lua Academy · Lesson

The debug Library

Inspect stack traces, locals, and upvalues with the debug library.

Lesson 4 of 413 steps

The debug Library is a free Lua Academy lesson on CoddyKit. This is lesson 4 of 4. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the Lua Academy learning path, and your progress syncs across the web and the CoddyKit app. The Lua Academy course includes 4 lessons in total.

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())  -- 99

debug.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?

Answer it in the interactive lesson

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.

Free to start

Learn Lua with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 40
Lessons: 159

Start learning free View the full course

Frequently Asked Questions

Is the “The debug Library” lesson free?

Yes — any 3 lessons of the Lua Academy learning path, including “The debug Library”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The Lua Academy course includes 4 lessons in total.

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, so you can start here or from the beginning and move at your own pace. This is lesson 4 of 4.

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

← Back to Lua Academy