How to Debug in Business Central (AL): Breakpoints, Attach & Snapshot

I have received several friends query related to Debug the AL language code of Business Central inside Visual Studio code. In order to help those dedicating this post.

Sooner or later, every Business Central developer hits a bug that reading the code alone will not solve. That is when debugging earns its keep. Being able to pause the code, inspect variables, and step through logic line by line turns hours of guesswork into minutes of certainty.

Business Central gives you three ways to debug, each suited to a different situation. This guide walks through all of them in plain terms: the setup you need, regular debugging with breakpoints, attaching to a live process, snapshot debugging for problems you cannot easily reproduce, plus the shortcuts and common fixes that save time. Let us get into it.

What You Need First

Before you can debug, make sure these are in place:

• Visual Studio Code, the tool where all AL debugging happens.
• AL Language extension installed in VS Code (this enables AL development and debugging).
• A Business Central environment you can reach: a cloud sandbox, cloud production (for snapshot), or an on-premises server.
• Symbol files downloaded for the base application and any dependencies (VS Code prompts you, or use the download symbols command).
• Debug permission. Your user needs the right to debug. For on-premises, the D365 AL DEVELOPER permission set is commonly used; for snapshot debugging on SaaS, the user must be in the D365 SNAPSHOT DEBUG group.

With those ready, everything is driven by one file: launch.json, in your project’s .vscode folder. It tells VS Code which environment to connect to and how to debug. You can hold several configurations in it and pick one when you start.

The Three Ways to Debug

Pick the method that matches your situation:

1. Regular Debugging (Breakpoints)

This is the one you will use most. The idea is simple: mark a line, run the code, and it pauses there so you can look inside.

Steps:

1. Open your AL project folder in VS Code.
2. Set a breakpoint by clicking in the left margin next to a line of code. A red dot appears.
3. Press F5. VS Code compiles, publishes your extension, opens the web client, and attaches the debugger.
4. In Business Central, perform the action that runs your code. Execution stops at your breakpoint.
5. Inspect variables in the VARIABLES pane, hover over values, and step through with the debug controls.

2. Attach Debugging (Catch a Live Process)

Sometimes you do not want to publish and trigger the code yourself. Maybe the bug happens during a web service call, a scheduled task, or another user’s session. Attach debugging lets you connect to the server and wait for the next matching process to hit your breakpoint.

How it works: add an attach configuration to launch.json, make sure your app is already published (Ctrl + F5), set your breakpoints, then start the attach session with F5 and choose the attach configuration. The debugger waits, and stops when a new session runs the code.

A key point: pressing refresh (F5) in the browser may not create a new server session because it can be cached. To reliably trigger it, launch a fresh client session, or invoke the web service call. Here is a minimal attach configuration:

{
    "name": "AL: Attach to Sandbox",
    "request": "attach",
    "type": "al",
    "environmentType": "Sandbox",
    "environmentName": "YourSandbox",
    "breakOnNext": "WebClient",
    "breakOnError": "ExcludeTry"
}

The breakOnNext value tells the debugger what kind of session to catch: WebClient for a user session, or WebServiceClient for an API or web service call. That makes attach ideal for debugging integrations.

3. Snapshot Debugging (Record and Replay)

The hardest bugs are the ones you cannot reproduce, especially in production where you cannot just set breakpoints and step through live code. Snapshot debugging solves this. It records the AL code as it executes, and afterwards you replay the recording in VS Code and inspect it like a normal debug session.

The flow:

1. Add a snapshotInitialize configuration to launch.json (see below).
2. In VS Code, start recording: press F7, or run AL: Initialize Snapshot Debugging from the command palette.
3. In Business Central, play out the use case, for example reproduce the error a user reported.
4. Back in VS Code, stop recording with Alt + F7 (Finish Snapshot Debugging).
5. Open the snapshots list (the toolbar button or Shift + F7) and replay it. The gutter shows which lines actually ran, and you can inspect variables at each step.

A snapshot configuration for a cloud environment looks like this:

{
    "name": "AL: Snapshot (cloud)",
    "request": "snapshotInitialize",
    "type": "al",
    "environmentType": "Sandbox",
    "environmentName": "YourSandbox",
    "breakOnNext": "WebClient",
    "executionContext": "DebugAndProfile"
}

Snapshot debugging can even target web service (service to service) calls by setting breakOnNext to WebServiceClient, which is invaluable for tracing integration errors you cannot step through live.

Shortcut: Start Debugging From the Web Client

Here is a genuinely useful modern feature. From Business Central itself, you can jump straight into a VS Code debug session for a problem you are looking at, without manually building a project first.

In the web client, open Help and Support, then look for the troubleshooting / inspect options. Business Central can open VS Code, and it automatically installs AL Language, generates the launch.json pointed at the current environment, and downloads the symbols for you. You then choose the debugging type (snapshot, regular, or none) and the session starts. It removes most of the manual setup and is great for consultants investigating a live issue quickly.

Handy Debugging Shortcuts

Common Problems and Fixes

Breakpoint not hit / shows as hollow. Usually the symbols do not match the running code. Republish your extension, and make sure you set breakpoints in your own code (debugging base app code needs those symbols too).

A variable shows “…” and looks empty. It is truncated because it is over 1024 bytes. Inspect it in the DEBUG CONSOLE by typing its name, rather than trusting the VARIABLES pane.

Attach never triggers. A cached browser refresh may not start a new server session. Open a fresh client session or invoke the web service directly, and confirm your breakOnNext matches the session type (WebClient vs WebServiceClient).

Snapshot debugging will not start on SaaS. Check the debugging user is in the D365 SNAPSHOT DEBUG group and that you selected the snapshot configuration (not your normal publish one).

Cannot debug at all. Confirm the AL Language extension is installed, symbols are downloaded, and your user has debug permission (for example D365 AL DEVELOPER on-premises).

FAQ, Debugging in Business Central

How do I start debugging in Business Central?
Open your AL project in VS Code, set a breakpoint by clicking the left margin of a code line, then press F5. VS Code publishes your extension and attaches the debugger, and execution stops at your breakpoint when you run that code in Business Central.

What is the difference between regular, attach, and snapshot debugging?
Regular debugging publishes and runs your code so you can step through it. Attach connects to an existing process (like a web service or another session). Snapshot records code as it runs, so you can replay and inspect it later, ideal for production issues you cannot reproduce.

Can I debug Business Central production (SaaS)?
Yes, using snapshot debugging. You record the execution in production and replay it in VS Code. The debugging user must be in the D365 SNAPSHOT DEBUG group, and you configure it with a snapshotInitialize entry in launch.json.

What is launch.json used for?
It is the configuration file (in your project’s .vscode folder) that tells VS Code which environment to connect to and how to debug. It can hold multiple configurations, for publishing, attaching, and snapshot debugging, and you choose one when you start.

Why is my breakpoint not being hit?
Most often the published code and symbols are out of sync. Republish the extension, ensure symbols are downloaded, and confirm the breakpoint is on code that actually runs for your action.

Can I debug an agent session?
Yes, in recent AL Language versions (2026 release wave 1, runtime 17.0 and later). A new Agent client type and attach configurations let you debug the AL code an agent runs, on a cloud sandbox or your own server.

Do I need special permissions to debug?
Yes. On-premises typically needs the D365 AL DEVELOPER permission set. Snapshot debugging on SaaS needs membership of the D365 SNAPSHOT DEBUG group.

Final Thoughts

Debugging in Business Central comes down to choosing the right tool for the situation. Reach for regular debugging when you can reproduce the issue, attach when you need to catch a live process or web service, and snapshot when the bug hides in production or refuses to reproduce. All three run through VS Code and the launch.json file, so once you are set up, switching between them is quick.

Get comfortable with breakpoints and the DEBUG CONSOLE first, then add attach and snapshot to your toolkit. Together they will resolve the vast majority of AL issues you will ever meet.

Stay tuned to NavisionPlanet for more practical Business Central and AL development guides drawn from real project experience.

Note: AL tooling changes between versions. Some options (such as agent session debugging) require recent AL Language extension and runtime versions. Confirm current details on Microsoft Learn for your specific version.