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.
Server-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 @AuraEnabled (documentation).
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.
The 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.
Client-side errors
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 SUCCESS and ERROR states.
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 response .getError().
Throwing and catching client-side errors
Client-side errors take the form of a JavaScript Error being thrown. An Error is very similar to Apex Exception: It’s a type built with a constructor, and it supports the same throw-catch syntax.
Just like Apex Exceptions, JavaScript Errors enable you to separate result values from errors when you call a function. For instance, if you follow best practices and let your helper do the heavy-lifting, you can write code like this in your controller:
Custom client-side errors
If a text message is not enough data to describe your error, you can extend the JavaScript standard Error type and create errors with custom attributes.
You can then throw it and catch it with this code.
Closing words
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?
