{"title":"Debug AL code","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/devenv-debugging/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-debugging, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/developer/devenv-debugging","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Debug AL code in Visual Studio Code by using breakpoints, attach sessions, record-write breaks, SQL statistics, and debugger settings.","date":"2026-10-07","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Debug AL code","slug":"debug-al-code","at":0,"chars":11045},{"level":2,"title":"Limitations to be aware of","slug":"limitations-to-be-aware-of","at":929,"chars":522},{"level":2,"title":"Breakpoints","slug":"breakpoints","at":1451,"chars":1176},{"level":3,"title":"Conditional breakpoints","slug":"conditional-breakpoints","at":2435,"chars":192},{"level":2,"title":"Break on errors","slug":"break-on-errors","at":2627,"chars":453},{"level":2,"title":"Break on record changes","slug":"break-on-record-changes","at":3080,"chars":955},{"level":2,"title":"Debugging large size variable values","slug":"debugging-large-size-variable-values","at":4035,"chars":250},{"level":2,"title":"Attach and debug next","slug":"attach-and-debug-next","at":4285,"chars":319},{"level":2,"title":"Debugging shortcuts","slug":"debugging-shortcuts","at":4604,"chars":968},{"level":2,"title":"Debug SQL behavior","slug":"debug-sql-behavior","at":5572,"chars":3524},{"level":3,"title":"View database statistics","slug":"view-database-statistics","at":5831,"chars":1021},{"level":3,"title":"View locks held","slug":"view-locks-held","at":6852,"chars":256},{"level":3,"title":"View SQL statement statistics","slug":"view-sql-statement-statistics","at":7108,"chars":1988},{"level":2,"title":"Debugging web services","slug":"debugging-web-services","at":9096,"chars":329},{"level":2,"title":"NonDebuggable attribute","slug":"nondebuggable-attribute","at":9425,"chars":159},{"level":2,"title":"Authenticate with Microsoft Entra ID on Business Central on-premises","slug":"authenticate-with-microsoft-entra-id-on-business-central-on-premises","at":9584,"chars":276},{"level":2,"title":"Troubleshooting your debugging setup","slug":"troubleshooting-your-debugging-setup","at":9860,"chars":1025},{"level":3,"title":"Firewall settings for port 7049 in on-premises environments","slug":"firewall-settings-for-port-7049-in-on-premises-environments","at":10002,"chars":278},{"level":3,"title":"Debug an online environment with an Embed app published in it","slug":"debug-an-online-environment-with-an-embed-app-published-in-it","at":10280,"chars":238},{"level":3,"title":"Launching debug sessions to on-premises environments","slug":"launching-debug-sessions-to-on-premises-environments","at":10518,"chars":367},{"level":2,"title":"Related information","slug":"related-information","at":10885,"chars":160}],"text":"# Debug AL code\n> NOTE\n> We're working to improve the onboarding experience for AL developers. If you have feedback about this article, use the Feedback section at the bottom of the article to tell us what you'd like to see.\n> We also welcome contributions to our documentation. Learn more about contributing in Contribute to the help<../help/contributor-guide#contributing>.\nDebugging is the process of finding and correcting errors. Visual Studio Code and the AL Language extension for Microsoft Dynamics 365 Business Central provide an integrated debugger that helps you inspect code and verify that your application runs as expected. Press F5 to start a debugging session. Learn more about Visual Studio Code debugging in https://code.visualstudio.com/docs/editor/debugging.\nAn alternative to classic debugging is snapshot debugging, which allows you to record running code and debug it later. See devenv-snapshot-debugging.\n## Limitations to be aware of\n You can debug external code only if the code has the allowDebugging flag set to true. Learn more about this setting in Resource exposure policy<devenv-security-settings-and-ip-protection>.\n By default, starting a launch debugging session opens the web client because launchBrowser is true.\n Pausing the debugging session isn't supported.\nTo control table data synchronization between each debugging session, see Retaining table data after publishing<devenv-retaining-data-after-publishing>.\n## Breakpoints\nThe basic concept in debugging is the breakpoint, which is a mark that you set on a statement. When the program flow reaches the breakpoint, the debugger stops execution until you instruct it to continue. Without any breakpoints, the code runs without interruption when the debugger is active. You can set a breakpoint by using the Debug Menu in Visual Studio Code. See #debugging-shortcuts.\nYou can set breakpoints in external code that isn't part of your project when its resource exposure policy allows debugging. Use Go to Definition to open the referenced code, which is generally a `.dal` file, and set a breakpoint. You can also step into the external code during a debugging session and set a breakpoint.\nThe following video shows how to set a breakpoint in the external Customer.dal file referenced by an AL project.\n![Visual Studio Code debugger stopped at a breakpoint in an external AL file.]\nLearn more about Go to Definition in devenv-al-code-navigation.\n### Conditional breakpoints\nIf a breakpoint condition evaluates to true, code execution stops at the breakpoint. See Setting conditional breakpoints<devenv-debugging-conditional-breakpoints>.\n## Break on errors\nUse the breakOnError property to specify whether the debugger breaks on the next error. If the debugger is set to breakOnError, it stops execution on both errors that are handled in code and unhandled errors.\nThe default value of breakOnError is All. Other supported values are None and ExcludeTry. To prevent the debugger from breaking on errors, set the property to None. The older Boolean values remain accepted for compatibility.\n## Break on record changes\nUse the breakOnRecordWrite property to specify whether the debugger breaks on record changes. If the debugger is set to break on record changes, it breaks before creating, modifying, or deleting a record. The following table shows each record change and the AL methods that cause each change.\nRecord change|AL Methods\nCreate a new record|methods-auto/record/record-insert--method\nUpdate an existing record|methods-auto/record/record-modify-method, methods-auto/record/record-modifyall-method, methods-auto/record/record-rename-method\nDelete an existing record|methods-auto/record/record-delete-method, methods-auto/record/record-deleteall-method\nThe default value of breakOnRecordWrite is None. Set it to All to break on all supported record changes, or ExcludeTemporary to ignore writes to temporary records. The older Boolean values remain accepted for compatibility. Learn more about these values in devenv-json-launch-file.\n## Debugging large size variable values\nString values longer than 1,024 characters are truncated with an ellipsis in the VARIABLES pane. To inspect the full value, enter the variable name or qualified name in the DEBUG CONSOLE, and then press Enter.\n## Attach and debug next\nIf you don't want to publish and invoke the functionality to debug it, you can attach a session to a specified server and await a process to trigger the breakpoint you have set. This is useful when you want to debug a specific process, such as a web service call. See devenv-attach-debug-next.\n## Debugging shortcuts\nKeystroke|Action\nF5|Start debugging\nCtrl+F5|Start without debugging. During an active debugging session, publish the existing extension without rebuilding.\nShift+F5|Stop debugging\nCtrl+Shift+F5|Start debugging without publishing.<br><br>If the code changed after it was last published, existing breakpoints might map to incorrect lines. For example, if you add two lines to a published method and set a breakpoint on the second new line, the server uses line mappings from the last published code. As a result, the breakpoint might not be hit or might stop on a different line.\nAlt+F5|Start RAD with debugging. See Working with Rapid Application Development<devenv-rad-publishing>.\nF10|Step over\nF11|Step into\nShift+F11|Step out\nF12|Go To Definition\nLearn more about shortcuts in Debugging in Visual Studio Code<https://code.visualstudio.com/docs/editor/debugging>. Learn more about working with Snapshot debugging in devenv-snapshot-debugging.\n## Debug SQL behavior\nThe AL debugger can examine your AL code's effect on the Business Central database. The enableSqlInformationDebugger setting enables this functionality and defaults to true. Learn more about debugger settings in devenv-json-launch-file.\n### View database statistics\nIn the debugger's VARIABLES pane, expand the \\<Database statistics\\> node to view database statistics. These statistics include network latency, executed SQL statements, rows read, held locks, and details about recent SQL statements.\nInsight|Description\nCurrent SQL latency (ms)|When the debugger hits a breakpoint, the Business Central Server sends a short SQL statement to the database, and measures the time it takes. The value is in milliseconds.\nNumber of SQL Executes|This number shows the total number of SQL statements executed in the debugging session since the debugger was started.\nNumber of SQL Row Reads|This number shows the total number of rows read from the Business Central database in the debugging session since the debugger started.\n> TIP\n> You can also get database insights from the AL runtime by using the methods-auto/sessioninformation/sessioninformation-sqlstatementsexecuted-method and methods-auto/sessioninformation/sessioninformation-sqlrowsread-method methods.\n### View locks held\nThe Locks section shows the SQL locks held by the debugged session and each lock's access mode. Use this information to understand locks acquired as you step through AL code and evaluate concurrency compatibility with other operations.\n### View SQL statement statistics\nThe database insights show the most recently executed SQL statements and the latest long-running SQL statements. To view a list of the statements, expand either the \\<Last Executed SQL Statements\\> or \\<Last Long Running SQL Statements\\> node. The following insights are part of the SQL statement statistics:\nInsight|Description\nStatement|The SQL statement that the AL server sent to the Business Central database. For further analysis, you can copy the SQL statement into other database tools, such as SQL Server Management Studio.\nExecution time (UTC)|The UTC timestamp for the SQL statement. Use this value to determine whether the statement ran between the current breakpoint and the previous breakpoint, if one is set.\nDuration (ms)|The total execution time of the SQL statement, measured inside the Business Central Server. Use Duration (ms) to identify potentially missing Business Central keys or to test the performance effects of database partitioning and compression.\nApprox. Rows Read|This number shows the approximate number of rows read from the Business Central database by the SQL statement. You can use this insight to analyze whether you're missing filters.\nThe numberOfSqlStatements setting in launch.json controls the number of SQL statements that the debugger tracks and defaults to `10`. The launch configuration also provides enableLongRunningSqlStatements and longRunningSqlStatementsThreshold. For on-premises environments, corresponding server settings can control the available SQL statistics.\n> NOTE\n> For Business Central on-premises, Business Central Server configuration settings control the SQL statistics available in the debugger. These settings determine whether the debugger shows SQL statements and long-running SQL statements. Check the server configuration if the expected insights don't appear. See Configuring Business Central server<../administration/server-instance-settings#manage-extensions-and-development>.\n## Debugging web services\nYou can debug code that runs from web service endpoints, including pages and codeunits exposed as OData or SOAP web services, and API pages and queries. Set breakOnNext to WebServiceClient and trigger the endpoint from an API explorer tool or your web service client code. See devenv-attach-debug-next.\n## NonDebuggable attribute\nThe NonDebuggable attribute can restrict debugging for certain methods or variables. See attributes/devenv-nondebuggable-attribute.\n## Authenticate with Microsoft Entra ID on Business Central on-premises\nYou can use Microsoft Entra ID as the authentication mechanism for Business Central on-premises or containers. See Microsoft Entra authentication for Business Central on-premises<devenv-aad-auth-onprem>.\n## Troubleshooting your debugging setup\nThis section provides some tips and tricks for working with and troubleshooting your debugging setup.\n### Firewall settings for port 7049 in on-premises environments\nTo use the development environment and debugger for on-premises environments, ensure that port `7049`, the default debugger port, is open. You can change the port by using the DeveloperServicesPort server setting.\n### Debug an online environment with an Embed app published in it\nFor an existing online environment with an Embed app, specify the applicationFamily property in launch.json. You define the application family during Embed app onboarding.\n### Launching debug sessions to on-premises environments\nFor on-premises launch configurations, usePublicURLFromServer defaults to true, which opens the browser by using the server's PublicWebBaseURL. Set it to false to use the server URL from launch.json instead. Learn more about this setting in devenv-json-launch-file#publish-to-local-server-settings-launchjson.\n## Related information\ndevenv-attach-debug-next\ndevenv-snapshot-debugging\nDeveloping extensions<devenv-dev-overview>\ndevenv-json-files\ndevenv-al-code-navigation"}