This article deals with error handling for Aura components and will only be valuable for developers creating or maintaining custom UI using that framework. If you are looking for Lightning Web Components (LWC) error handling, please see our updated blog post from 2020.
Sending a request from a Lightning component to an Apex Controller and getting back a response is a path that has several potential failure points. Developers sometimes assume for the sake of simplicity that “things will work” and don’t always perform all the proper error checks and handling. In this blog post we look at best practices for handling server-side and client-side errors.
Client-server communication overview
The Lightning Component framework is a client framework. It relies on Apex to perform backend operations such as accessing data.
Exchanges between the two sides follow a common request-response pattern.
- A Lightning component sends a request to its Apex controller using a server-side action.
- The controller processes the request. This can trigger a server-side error (permission issue, invalid query).
- The controller sends a response to the Lightning component.
- The Lightning component processes the response in a callback function. This can trigger a client-side error (unexpected response).
If we omit the network-related errors, this pattern can trigger two types of errors that developers must handle: server-side and client-side errors.
Quick refresher on Apex server-side controller
The Lightning Component framework communicates with Apex via server-side actions. These actions are declared as
static methods annotated with
What to avoid
Processing a server request can trigger errors due to a variety of causes such as permission issues, invalid queries, or Apex limits being reached. These errors take the form of an Exception being thrown in the Apex code.
If you process a failing server request as is (see code below), a system exception is returned to the Lightning component.
Doing so is bad practice as this results in a generic error message: “An internal server error has occurred” or “Sorry to interrupt”. This is not user-friendly and provides no information about the error. We all hate that. 🙁
Basic error handling
Thankfully, the solution to this problem is quite simple.
- Wrap the code that can trigger exceptions in a try-catch block.
- Throw an
AuraHandledExceptionin the catch block. This allows you to provide a custom user-friendly error message.
Here is the code of the previous example updated with this best practice.
AuraHandledException is sent back to the client with your custom message, and you’re free to display it in the way you want using the Lightning Component framework.
Custom error handling
The previous solution is good enough for basic error handling, but what if you have a complex processing logic and require more information about the error on the client-side? How about adding an exception name and an error code?
Unfortunately, you cannot extend
AuraHandledException to create a custom exception because it is not an extensible Apex class. However, there is a trick that can help you bypass this limitation.
You can add custom data to your
AuraHandledException by following these steps.
- Create a simple wrapper class that can hold the data.
- Instantiate your custom class, serialize it as JSON, then pass it to the AuraHandledException.
- Finally, on the client-side (Lightning controller or helper), parse the error message string as JSON, and access your custom error data.
Processing a response on the client-side can trigger several types of errors as well. These typically occur when the client receives an answer from the server that does not meet its expectations. This can be caused by a remote technical error such as an
AuraHandledException or a value that does not meet certain business rules.
Quick refresher on Lightning Server-Side Actions
The Lightning Component framework uses Server-Side Actions to perform requests on Apex controllers. This is done in five steps.
For the sake of brevity, we only focus on the callback function in this article. It exposes one argument that is an object holding the response sent by the server.
The first thing to do upon entering the callback function is to check the response state with
response.getState(). This function can return different state values, but you should at least check for
Handling a server error
If the state of the response is
ERROR, you need to handle a server error. You can access the errors details with the
response.getError() function, but there’s a catch: Despite its name, this function returns an array of errors, not just a single one.
In most of the cases, you want to check the first error of this array, but keep in mind that there can be more than one. Here’s the minimal code that covers that.
Note that you should avoid using
console.log() to report errors. Use
console.error() instead. This ensures that your errors are properly reported in your browser’s developer tools. It’s easy to miss an error in a stack full of info or debug messages.
Reporting the error in the console is a start, but the end goal is to display it to the user. The easiest way to do this if you’re working on a page that’s rendered in Lightning Experience is to display a Lightning Toast notification. You can do so by calling the following helper function while passing it the return value of
Throwing and catching client-side errors
Custom client-side errors
Error type and create errors with custom attributes.
You can then throw it and catch it with this code.
We’ve covered the different types of errors that can occur when processing client-server communications. You now know how to handle those different errors and how to extend them to fit your needs.
How about trying those different options in an interactive playground and studying some sample code?