In this video, I go through the AL debugger and cover the most common features of debugging AL code. This is another video in my series AL for beginners.
In this video, Erik walks through the fundamentals of AL debugging in Business Central — covering the three essential components that must work together, how to set and manage breakpoints, navigating code execution with step controls, and multiple ways to inspect variables. Whether you’re brand new to debugging or just haven’t explored all the tools available, this guide covers the practical techniques you’ll use in the vast majority of your debugging sessions.
The Three Components of Debugging
The first thing to understand about AL debugging is that there are three distinct components that must work together:
- The Business Central Server — the backend that executes your AL code
- Visual Studio Code — your development environment where you set breakpoints and inspect code
- The Browser — the client where you interact with Business Central
These three need to be in sync, and the mechanism that ties them together is the debugging context.
The Debugging Context
When you press F5 in VS Code to start debugging, it opens a browser window with a special URL that includes a debugging context parameter. This context is what links your VS Code session to that specific browser tab through the BC server.
This is a critical concept: if you open another browser tab and navigate to the same Business Central environment manually, that tab will not have the debugging context. Any actions you perform in that tab will never trigger your breakpoints. Only the tab opened by VS Code — the one with the debugging context — will cause the debugger to break.
Your launch.json configuration specifies the server and instance you’re connecting to. VS Code uses this information to establish the debugging session and open the browser with the correct context.
Setting Breakpoints
A breakpoint tells the debugger to pause execution at a specific line of code. There are two ways to set a breakpoint:
- Click in the gutter — click in the column to the left of the line number. A red dot appears indicating the breakpoint is set.
- Press F9 — with your cursor on the desired line, press F9 to toggle a breakpoint.
You can manage your breakpoints in the Debug panel on the left side of VS Code. The Breakpoints section shows all active breakpoints with their file and line number. From there, you can also delete individual breakpoints or remove all of them at once.
Execution Controls: Continue, Step Over, Step Into, Step Out
Once the debugger hits a breakpoint, the debug toolbar appears at the top of VS Code. The execution is paused, and you have several options for how to proceed:
Continue (F5)
Resumes execution normally until the next breakpoint is hit or the operation completes. This is straightforward — you’re done inspecting and want to let the code run.
Step Over (F10)
Executes the current line and moves to the next line in the same function. If the current line contains a function call, it executes that entire function without stepping into it. This is the option you’ll use most often — it lets you move through your code line by line without diving into every called function.
Step Into (F11)
If the current line contains a function call, Step Into will take you inside that function. This is useful when you need to see what’s happening inside a specific call, but be warned — it can be a time killer. You’ll quickly find yourself deep inside system code units, event subscribers, and framework code that has nothing to do with your problem.
For example, stepping into a field validation on a Sales Line can take you through notification lifecycle handlers, job planning line checks, and other system code you probably don’t care about.
Step Out (Shift+F11)
Step Out completes the execution of the current function and returns you to the calling function — essentially going back up one level in the call stack. This is your escape hatch when Step Into takes you somewhere irrelevant.
A Practical Workflow
Erik recommends the following approach: use Step Over as your default navigation. Only use Step Into when you specifically need to inspect a particular function call. If Step Into takes you somewhere irrelevant, use Step Out to get back, then continue with Step Over.
The Call Stack
When execution is paused, the Call Stack panel shows you the chain of function calls that led to the current point. It works like any stack data structure — each function call adds a layer on top, and as functions return, layers are removed.
You can click on any entry in the call stack to see the context at that level — the local variables, global variables, and the exact line of code where the call was made. This doesn’t change where execution is paused; it just changes what you’re viewing.
An important detail: the variables panel updates based on which call stack frame you’ve selected. Global variables are not truly global in the debugger — they are global in the context of the object you’re viewing in the call stack. So if you click on your custom page, you’ll see its global variables. If you click on a system code unit in the stack, you’ll see different globals (or none at all).
Similarly, function parameters are treated as local variables. If a function takes a parameter called item, that parameter will appear in the Locals section alongside any variables declared within the function.
Inspecting Variables: Four Methods
There are four ways to inspect variable values while debugging:
1. The Variables Panel
The Variables panel in the Debug sidebar shows local and global variables for the current call stack frame. It’s useful but has a tendency to collapse or rearrange when you step through code.
2. Watch Expressions
You can add watch expressions to persistently monitor specific values. Click the “+” in the Watch section and type the expression you want to monitor, such as:
item— shows the entire record, which you can expanditem.Number— shows a specific field valueSalesLine."Document No."— shows a field from another record
Watch expressions show “not available” when out of scope, but they persist across debugging steps, making them very useful for tracking values over time.
3. Mouse Hover
You can hover over variables in the code editor to see their values in a tooltip. However, Erik notes this can be inconsistent — hovering over a record variable might not show anything, hovering over the dot might show the record, and hovering over a field name can be confusing. It’s the least reliable of the four methods.
4. The Debug Console
This is arguably the most powerful method. Open the Debug Console panel at the bottom of VS Code and type variable names or expressions directly:
sl
sl.Quantity
item.NumberThe Debug Console has several advantages over the other methods:
- Long string values that get truncated in tooltips or the Variables panel are shown in full
- Results accumulate in the console, giving you a history of values — you can check a variable, step forward, check it again, and see both values in the output
- Press the up arrow to recall previous expressions, making it quick to re-evaluate
One limitation: you cannot modify variables through the Debug Console. Typing something like sl.Quantity := 10 won’t work. You can only read values, not change them.
Common Issues and Tips
Breakpoints That Won’t Set
Sometimes the Debug Console will report that it cannot set certain breakpoints. This typically happens with Docker images when the server gets confused. The fix is usually to delete all breakpoints, stop debugging, and restart the Docker container.
Errors the Debugger Won’t Catch
One frustrating limitation is that certain errors won’t cause the debugger to break. If you have a built-in validation error — not a direct Error() call in your code, but a system-generated error from something happening internally — the debugger may not pause on it. This is simply a limitation of the current debugging experience.
Publish vs. Publish and Debug
When you press F5, VS Code performs a “Publish and Debug” — it deploys your extension and starts a debugging session. You can also simply publish without debugging if you don’t need to step through code.
Summary
AL debugging in Business Central revolves around understanding the relationship between three components: the BC server, VS Code, and the browser, all linked through a debugging context. The core workflow involves setting breakpoints strategically, using Step Over as your primary navigation tool, Step Into only when you need to dig deeper, and Step Out to escape irrelevant code. For inspecting variables, the Debug Console is the most versatile tool, offering full values and a history of evaluations. While there are limitations — you can’t modify variables at runtime and some system errors won’t trigger breaks — these techniques cover the vast majority of real-world debugging scenarios in AL development.
