Error handling

Path: Development > Programming in the AL language > Error handling · tier official · system development · narrative reviewed (checked by Opus)

Overview

This section explains how AL code deals with errors from design to diagnosis. It starts with an overview of strategies (error dialogs, try methods, error collection, telemetry, the ErrorInfo data type and error message quality), then goes into each technique on its own page.

For writing code, the pages cover try methods with the TryFunction attribute, collectible errors using the ErrorBehavior attribute and the error collection API, and actionable errors built with ErrorInfo. Failure modeling and robust coding practices give the design principles behind these choices. The user experience guidelines page covers wording, voice and dialog best practices.

For diagnosis, the page on the error dialog explains what users see and what they can copy for support, such as the AL call stack and the Application Insights session ID. The Error telemetry subtopic goes further into analyzing error events in Application Insights. A subtopic with AL language reference pages for errors is also part of the section. Start with “AL error handling” for orientation.

Key points

• Actionable errors use ErrorInfo objects with Fix-it and Show-it actions, up to two actions per error, with consistent button labels and field validation support.
• Try methods use the TryFunction attribute, return a boolean, and can be inspected with GetLastErrorText and GetLastErrorObject; database write restrictions apply, and the page mentions runtime version 2.0.
• Collectible errors (ErrorBehavior attribute and error collection API) let a procedure gather several validation errors and show them together instead of stopping at the first.
• The error dialog has a Copy Details section with the AL call stack and the Application Insights session ID, useful for troubleshooting.
• Failure modeling lists six robust coding principles: do not trust external code, consumers or the environment; offer graceful degradation; hide internal data structures; assume improbable events happen at scale.
• UX guidelines cover actionable messages, message formatting, validation errors and voice for error text.
• Error telemetry covers event IDs, dimensions, KQL analysis, permission errors, user votes on error messages, and logging with the Telemetry AL module.

Subtopics

• Error telemetry (4 pages)
• AL language reference (errors) (5 pages)

More Learn pages

• Actionable errors: Learn how to write AL code that returns error dialogs where users might unblock themselves.
• AL error handling: Deal with unexpected situations that occur when code is run in AL for Business Central.
• Collecting Errors: Learn how to write AL code that returns more than one error and presents users with more detailed error information.
• Failure modeling and robust coding practices: Describes how to reason over errors and handle them in code.
• Handling errors using try methods: Try methods in AL enable you to handle errors that occur in the application during code execution.
• Understanding the error dialog: Understand the different parts the error dialog to be able to help mitigate issues for users
• User experience guidelines for errors: Describes how to handle error dialogs in AL code.

Videos, posts and code changes

Linked by a Haiku matcher with a grounding quote from the item’s summary (link/topics.ts); machine-generated.

• #12117 [Job Queue] Clearer message and attempt number for runs interrupted by the platform (code change): “confusing ‘job has stopped’ error message with ‘run was interrupted’ message”
• #99 Add lifecycle error and privacy knowledge (code change): “covering try-function semantics, upgrade phase data writes, install-versus-upgrade dispatch logic, ErrorInfo privacy”
• 🔧 Transforming BC Error Handling with Smart Recommendations 📝 (community post): “Event Subscribers intercept Business Central errors, validate tag matches, and invoke the ErrorMessageFix interface”
• How to Write Error Messages That Help (community post): “Error messages significantly impact user experience in enterprise software”
• BC Friday Tips #77 TestField Show Record Action (community post): “TestField automatically adds a Show Record button to error dialogs”

Source: Microsoft Learn (CC BY 4.0). Descriptions are Learn’s own.