Edit

AL error handling

  • Article

Note

We're working on improving the onboarding experience for AL developers. If you've input for this article, we'd love to hear from you. Please use the Feedback section at the bottom of this article to help us make improvements that you’d like to see.

We also welcome contributions to our docs. New to contributing to docs? Don't worry, read more about contributing here Contribute to the help.

The AL language has many error handling features, which can help you deal with unexpected situations that occur when code is run. This section contains articles about using these methods in AL to handle errors that occur during code execution, while making sure that your application has a consistent user interface.

The following articles discuss the different aspects of error handling in AL:

Error handling methods in AL

For examples of using different error handling methods in AL, see the following table:

Method Description
ClearLastError Method Removes the last error message from memory.
Dialog Data Type Represents a dialog window.
Error Method Displays an error message and ends the execution of AL code.
ErrorInfo Data Type Contains a set of methods that helps identify errors, classify these errors, send errors to telemetry and display UI messages. Go to the data type article for an overview.
System Data Type Is a complex data type and contains multiple methods for getting and classifying errors.
GetLastErrorCallStack Method Gets the call stack from where the last error occurred.
GetLastErrorCode Method Gets the classification of the last error that occurred.
GetLastErrorObject Method Gets the last System.Exception object that occurred.
GetLastErrorText Method Gets the last error that occurred in the debugger.

Tip

If you already know the name of a data type, use the Filter by title field in the upper left corner, above the table of contents to find the topic faster.

Error handling strategies

For examples of different error handling strategies, see the following table:

If you want to... Then use
Run a code unit and decide to do something if an error occurs. if not Codeunit.run(). For more information, see Codeunit.Run return value
Check for an error and show an error dialog to the user. Dialog.Error(Message: ErrorInfo). For more information, see Error Method.
Check for an error and show an error dialog to the user with added support information. Using the ErrorInfo Data Type with the Error Method
Do bulk validations in AL and not show an error dialog for each of them to the user. Collecting Errors
Catch errors raised by other AL methods Handling Errors using Try Methods
Catch errors/exceptions that are thrown during .NET framework interoperability operations (on-premises only). Handling .NET Exceptions using Try Methods
Handle errors happening in Page Background Tasks The OnPageBackgroundTaskError trigger of the page. For more information, see Handling errors (in Page Background Tasks).
Log an error that happens within a database transaction (that rollback) Either log the error in a new session using a background session, or log the error to telemetry (see LogMessage or Telemetry.LogError ).

Guidelines for error messages

Improving error handling and error messages reduces friction for the users and highly impacts the user experience. Clear, informative error messages help users understand what went wrong and how to correct it, reducing frustration, and improving user satisfaction.

For guidance on how to formulate good error messages, see Error message best practices - what to say?.

Error telemetry (emitted by the AL runtime)

When a user gets an error dialog while working in Business Central, a telemetry signal is emitted, which can be logged in an Azure Application Insights resource. This telemetry data let's you identify and analyze where and why the error occurs. You can also set up alerts in Azure Application Insights to get notified if many users experience errors.

There are three types of telemetry data emitted about errors

  • Error message quality
  • Error dialogs shown to users
  • Permission errors
If you want to... Then look at this telemetry
Understand if users understand the error messages they see. Error message quality telemetry
Understand which error dialogs users see and where in the AL code the error is raised. Error method telemetry
Understand when users get error dialogs about lack of permissions. Permission error telemetry

Error telemetry (emit your own)

You can emit your own telemetry about error situations by using the Telemetry AL module. Using this module, you can simplify the way you monitor the health of your app and also monitor the uptake and usage of application features.

For more information, see Telemetry.LogError.

See also

Failure modeling and robust coding practices
Understanding the error dialog
User experience guidelines for errors
Actionable errors
Collecting errors
Handling errors using Try methods
Handling errors (in Page Background Tasks)
Telemetry.LogError
Error message quality telemetry
Error method telemetry
Permission error telemetry
AL control statements
AL development environment