Debugging WoW Addons
Systematic debugging and error recovery for WoW addons.
Related Commands
- •c-debug - Reload loop workflow for finding and fixing issues
- •c-review - Full code review (includes debug step)
MCP Tools (Use These First)
MANDATORY: ALWAYS use MCP tools directly instead of the shell.
| Task | MCP Tool |
|---|---|
| Get All Output | addon.output(agent_mode=true) |
| Lint Addon | addon.lint(addon="MyAddon") |
| Scan Deprecations | addon.deprecations(addon="MyAddon") |
| Queue Lua Eval | lua.queue(code=["GetMoney()"]) |
| Get Eval Results | lua.results() |
Capabilities
- •Evidence-Based Debugging — Hypothesis-driven investigation with runtime instrumentation and log proof
- •Error Analysis — Parse Lua errors, identify root cause in stack traces
- •Taint Investigation — Track secure/insecure code interaction and "Action blocked" issues
- •Combat Issues — Debug lockdown-related failures and protected frame issues
- •API Failures — Handle deprecated or changed APIs (Midnight 12.0 prep)
Routing Logic
| Request type | Load reference |
|---|---|
| Evidence-based debugging, hypothesis-driven | references/evidence-based-debugging.md |
| Lua errors, nil values | references/error-patterns.md |
| Debug workflow, isolation | references/debugging-strategies.md |
| Error tracking (BugGrabber) | ../../docs/integration/errors.md |
| Troubleshooting guide | ../../docs/integration/troubleshooting.md |
| Structured logging | ../../docs/integration/console.md |
| Frame inspection | ../../docs/integration/inspect.md |
Debug Output Best Practice
CRITICAL: Use
MechanicLib:Log()instead ofprint()for all debug output.
| Feature | print() | MechanicLib:Log() |
|---|---|---|
| Agent access | ❌ Requires screenshot | ✅ addon.output retrieves directly |
| Filtering | ❌ None | ✅ Source + category filters |
| Copyable | ❌ No | ✅ Yes, via Console export |
lua
-- ✅ Correct: Agent can see this in addon.output
local MechanicLib = LibStub("MechanicLib-1.0", true)
if MechanicLib then
MechanicLib:Log("MyAddon", "Debug: value=" .. tostring(val), MechanicLib.Categories.CORE)
end
-- ❌ Avoid: Spams chat, requires screenshot
print("[MyAddon] Debug: value=" .. tostring(val))
Quick Reference
Get Addon Data (Compressed for AI)
Ask user to /reload and confirm, then:
bash
addon.output(agent_mode=true)
Common Error Patterns
- •
attempt to index nil value: API returned nil, check if unit exists or data is loaded. - •
Action blocked by Blizzard: You tried to call a protected function in combat. - •
Interface action failed: Taint has spread to a secure UI component.
Systematic Workflow
- •Gather Evidence: Ask user to
/reload, wait for confirmation, thenaddon.output(agent_mode=true) - •Isolate: Can you reproduce with minimal code?
- •Hypothesis: "If X then Y because Z"
- •Fix & Validate: Apply minimal fix, ask user to
/reloadand confirm, then verify withaddon.output.