Handle Errors from Apex

Apex throws different exceptions like DmlException or QueryException. You can use these Apex built-in exceptions or create a custom exception. You can also create and throw an AuraHandledException to handle the exception more gracefully in your JavaScript code. AuraHandledException is supported in LWC and Aura components.

When your Apex controller code encounters an error, you can use a try-catch block and handle the error in Apex. Otherwise, the error becomes unhandled and gets thrown directly to the client.

LWC Error Handling Best Practices

Handling Apex errors allow you to control the error details that are returned to the client. Consider this Apex method that uses a variable that returns null and throws an unhandled exception. Since we're not passing in the str parameter, str is null and str.toUpperCase() throws an exception.

The lwc-recipes repo has many examples that demonstrate error handling when retrieving data from Apex. Look for components that start with apex*, such as apexImperativeMethod.

The error is returned directly from Apex and surfaces the ErrorExamples class name in the body.stackTrace property.

You can throw and catch a custom exception using AuraHandledException or by defining a custom exception class that extends Exception.

The AuraHandledException returns a custom error message to a JavaScript controller on an Aura component. However, it's also supported on Lightning web components.

The error message includes your custom message and the one returned from Apex, which is available via e.getMessage(). But the error doesn't include the body.stackTrace property.

You can throw your own exception and pass in your own message, for example, using MyException. See Create Custom Exceptions.

The error message includes the line number and Apex class name that triggered the exception.

In some cases, you can choose to handle errors on the server and not return an exception to the client at all. For example, if you encounter an exception from a third-party call, you can handle the exception in Apex and not forward the error to the client.

This example uses the safe navigation operator to return the upper case of a given string only when the str variable is not null, or return null otherwise.

All the previous examples return an error using a string. To return a custom error object instead, create a wrapper class that defines the variables you want to include.

The error includes the variables you defined in the wrapper class.

Using a wrapper class to define your error structure can be helpful when you work with a team that needs to standardize their Apex errors.

When handling Apex errors, make sure the catch block considers different Apex exceptions. For example, handle DmlException and QueryException errors if you're working with DML and SOQL statements.

Consider these additional guidelines.

  • Split your code into different modules if you expect to handle multiple use cases. Don't place all code inside the try block.
  • If errors from different blocks must be handled in different ways, use multiple try-catch blocks.
  • Handle only the errors you expect to see in the catch block. The rest should be propogated further.

See Also