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

1. Evidence-Based Debugging — Hypothesis-driven investigation with runtime instrumentation and log proof
2. Error Analysis — Parse Lua errors, identify root cause in stack traces
3. Taint Investigation — Track secure/insecure code interaction and "Action blocked" issues
4. Combat Issues — Debug lockdown-related failures and protected frame issues
5. 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 of print() 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

-- ✅ 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:

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

1. Gather Evidence: Ask user to /reload, wait for confirmation, then addon.output(agent_mode=true)
2. Isolate: Can you reproduce with minimal code?
3. Hypothesis: "If X then Y because Z"
4. Fix & Validate: Apply minimal fix, ask user to /reload and confirm, then verify with addon.output.