skill-debug

Skill: AL Debugging & Diagnostics

Purpose

For BC29 AL0926 section-order errors or new isolation behavior, read the relevant sections of AL18 capability checks. Use actual compiler/runtime evidence and keep compilation distinct from execution.

Systematic diagnosis and root cause analysis for AL Business Central issues: runtime errors, logic bugs, intermittent failures, performance bottlenecks, and configuration problems.

When to Load

This skill should be loaded when:

• A runtime error, exception, or unexpected behavior is reported
• A logic bug needs root cause analysis (not just a symptom fix)
• An intermittent issue needs snapshot capture
• A performance bottleneck needs CPU profiling
• Configuration issues (auth, symbols, build, publishing) block development
• An event subscriber is not firing as expected

Core Patterns

Pattern 1: Choose Debugging Strategy

Select the right tool before starting:

Issue Type	Strategy	Tool
Consistent runtime error	Standard debugger	al_debug
Already deployed code	Debug without publish	al_debug
Rapid dev cycle	Incremental publish	al_publish (incremental)
Intermittent / hard-to-reproduce	Snapshot debugging	al_snapshotdebugging
Slow performance	CPU profiling	VS Code command (not an agent tool)
Auth / symbols / build	Configuration troubleshoot	See Workflow Step 2b
Copilot AI feature	Agent session debug	launch.json with clientType: Agent

Pattern 2: Data Flow Tracing

Scenario: "Value is wrong after posting"

1. Set breakpoint at final location (where value is wrong)
2. Work backwards to find where value is set
3. Use `usages` tool to find all assignments
4. Set breakpoints at each assignment point
5. Step through to find which execution path is taken
6. Inspect conditions and variable states at each point

Pattern 3: Event Subscriber Not Firing

Scenario: "My event subscriber doesn't execute"

1. Verify subscriber signature exactly matches publisher (name, parameters, types)
2. Check SkipOnMissingLicense and SkipOnMissingPermission attributes
3. Confirm the extension containing the publisher is active and published
4. Set breakpoint inside subscriber body
5. Verify the publisher event is actually being raised (breakpoint in publisher)
6. Check if IsHandled = true is set before your subscriber runs
7. Inspect subscriber execution order (EventPriority)