{"title":"Debugging tools - aldebug, alsetbreakpoint, alsnapshotdebugging","url":"https://jonas-paprotka.de/docs/dev-itpro/developer/al-agent-tools/al-tool-debug/","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/al-agent-tools/al-tool-debug, 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/al-agent-tools/al-tool-debug","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":"Learn about the debugging tools available for AL development, including how to use them in Visual Studio Code with GitHub Copilot and through the AL MCP Server for headless environments and CI/CD pipelines.","date":"2026-10-02","meta":{"topic":"concept-article"},"outline":[{"level":1,"title":"Debugging tools - al_debug, al_setbreakpoint, al_snapshotdebugging","slug":"debugging-tools---al_debug-al_setbreakpoint-al_snapshotdebugging","at":0,"chars":4279},{"level":2,"title":"al_debug - Start a debug session","slug":"al_debug---start-a-debug-session","at":396,"chars":724},{"level":3,"title":"Parameters","slug":"parameters","at":801,"chars":21},{"level":3,"title":"Return value","slug":"return-value","at":822,"chars":122},{"level":3,"title":"Example","slug":"example","at":944,"chars":176},{"level":2,"title":"al_setbreakpoint - Set or remove a breakpoint","slug":"al_setbreakpoint---set-or-remove-a-breakpoint","at":1120,"chars":1389},{"level":3,"title":"Parameters","slug":"parameters-1","at":1468,"chars":441},{"level":3,"title":"Return value","slug":"return-value-1","at":1909,"chars":124},{"level":3,"title":"Examples","slug":"examples","at":2033,"chars":476},{"level":2,"title":"al_snapshotdebugging - Manage snapshot debugging sessions","slug":"al_snapshotdebugging---manage-snapshot-debugging-sessions","at":2509,"chars":1448},{"level":3,"title":"Parameters","slug":"parameters-2","at":2891,"chars":313},{"level":3,"title":"Return value","slug":"return-value-2","at":3204,"chars":84},{"level":3,"title":"Examples","slug":"examples-1","at":3288,"chars":267},{"level":3,"title":"Snapshot debugging workflow","slug":"snapshot-debugging-workflow","at":3555,"chars":402},{"level":2,"title":"Related tools","slug":"related-tools","at":3957,"chars":212},{"level":2,"title":"Related information","slug":"related-information","at":4169,"chars":110}],"text":"# Debugging tools - al_debug, al_setbreakpoint, al_snapshotdebugging\nApplies to: AL Language extension 17.0 and later | Available in: Visual Studio Code only\nThree tools support debugging AL extensions inside Visual Studio Code. All three are available only in Visual Studio Code (not in the AL MCP Server), because they interact directly with the Visual Studio Code debugger and Problems panel.\n## al_debug - Start a debug session\nThe al_debug tool starts a debug session that attaches to an already-published AL extension without triggering a new publish. This is equivalent to the Start Without Publishing action in Visual Studio Code.\nUse this tool when your extension is already deployed and you want to attach the debugger to investigate a specific issue without the overhead of a full publish.\n### Parameters\nNone.\n### Return value\nA message string indicating that the debug session started, or an error message if the operation failed.\n### Example\nIn Copilot Chat: \"Start debugging without republishing.\"\nCopilot calls al_debug. If no debug configuration is active, Visual Studio Code prompts you to select one.\n## al_setbreakpoint - Set or remove a breakpoint\nThe al_setbreakpoint tool programmatically adds, removes, or toggles a breakpoint at a specific line in an AL source file. This lets an agent set targeted breakpoints as part of an automated debugging workflow-for example, after analyzing an error to determine exactly where execution should pause.\n### Parameters\nParameter|Type|Default|Required|Description\nfilePath|string|-|Yes|Absolute path to the `.al` file where the breakpoint should be placed.\nlineNumber|integer|-|Yes|The line number (1-based) at which to set the breakpoint.\naction|`\"toggle\"` \\| `\"add\"` \\| `\"remove\"`|`\"toggle\"`|No|The action to perform: `\"add\"` creates the breakpoint unconditionally, `\"remove\"` deletes it, `\"toggle\"` adds it if absent or removes it if present.\n### Return value\nA string describing the outcome (for example, `\"Breakpoint added at line 42 in CustomerMgt.Codeunit.al\"`).\n### Examples\nSet a breakpoint at line 42 (Copilot Chat):\n\"Set a breakpoint on line 42 of CustomerMgt.Codeunit.al.\"\nCopilot calls al_setbreakpoint with `action=\"add\"` and `lineNumber=42`.\nRemove a breakpoint:\n```json\n{\n  \"filePath\": \"C:/repos/MyExtension/src/CustomerMgt.Codeunit.al\",\n  \"lineNumber\": 42,\n  \"action\": \"remove\"\n}\n```\nToggle a breakpoint:\n```json\n{\n  \"filePath\": \"C:/repos/MyExtension/src/CustomerMgt.Codeunit.al\",\n  \"lineNumber\": 100,\n  \"action\": \"toggle\"\n}\n```\n## al_snapshotdebugging - Manage snapshot debugging sessions\nThe al_snapshotdebugging tool manages snapshot debugging sessions. Snapshot debugging lets you capture execution traces from live environments - including production - without interrupting users or requiring a connected debug session. After the snapshot is collected, you can step through the recorded execution offline.\n### Parameters\nParameter|Type|Required|Description\naction|`\"initialize\"` \\| `\"finish\"` \\| `\"view\"`|Yes|The action to perform: `\"initialize\"` starts a new snapshot capture, `\"finish\"` ends the current capture and saves the trace, `\"view\"` opens the Snapshots view in Visual Studio Code to inspect recorded traces.\n### Return value\nA command result object or a string indicating success or failure.\n### Examples\nStart a snapshot capture:\n```json\n{\n  \"action\": \"initialize\"\n}\n```\nEnd the capture:\n```json\n{\n  \"action\": \"finish\"\n}\n```\nOpen the snapshots view:\nIn Copilot Chat: \"Show me the captured snapshots.\"\nCopilot calls al_snapshotdebugging with `action=\"view\"`.\n### Snapshot debugging workflow\n1. Call al_snapshotdebugging with `action=\"initialize\"` to start capturing.\n2. Reproduce the scenario you want to investigate in Business Central.\n3. Call al_snapshotdebugging with `action=\"finish\"` to stop the capture and save the trace.\n4. Call al_snapshotdebugging with `action=\"view\"` to open the trace in Visual Studio Code and step through the recorded execution.\n## Related tools\n al_publish<al-tool-publish> - Deploy the extension before starting a debug session.\n al_getdiagnostics<al-tool-get-diagnostics> - Review compilation errors to identify where to set breakpoints.\n## Related information\nAI agent tools overview<al-agent-tools-overview>\nAL MCP Server reference<al-mcp-server>"}