Lightning Aura Components Developer Guide

What Is the Lightning Component Framework?
Quick Start
Creating Components
Using Components
Communicating with Events
Communicating Across the DOM with Lightning Message Service
Creating Apps
Styling Apps
Developing Secure Code
Using JavaScript
Working with Salesforce Data
Lightning Data Service
Using Apex
Creating Server-Side Logic with Controllers
Apex Server-Side Controller Overview
AuraEnabled Annotation
Creating an Apex Server-Side Controller
Using Apex to Work with Salesforce Records
Granting User Access for Apex Classes
Securing Data in Apex Controllers
Calling a Server-Side Action
Passing Data to an Apex Controller
Returning Data from an Apex Server-Side Controller
Returning Errors from an Apex Server-Side Controller
Queueing of Server-Side Actions
Foreground and Background Actions
Storable Actions
Abortable Actions
Testing Your Apex Code
Making API Calls from Apex
Make Long-Running Callouts with Continuations
Creating Components in Apex
Testing Components with Lightning Testing Service
Debugging
Performance
Reference
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Returning Errors from an Apex Server-Side Controller

Create and throw a System.AuraHandledException from your Apex controller to return a custom error message to a JavaScript controller.

Errors happen. Sometimes they’re expected, such as invalid input from a user, or a duplicate record in a database. Sometimes they’re unexpected, such as... Well, if you’ve been programming for any length of time, you know that the range of unexpected errors is nearly infinite.

When your Apex controller code experiences an error, two things can happen. You can use a catch block and handle the error in Apex. Otherwise, the error is passed back in the controller’s response.

If you handle the error in Apex, you again have two ways you can go. You can process the error in a catch block, perhaps recovering from it, and return a normal response to the client. Or, you can create and throw an AuraHandledException.

The benefit of throwing AuraHandledException, instead of letting a system exception be returned, is that you have a chance to handle the exception more gracefully in your JavaScript controller code. System exceptions have important details stripped out for security purposes, and result in the dreaded “An internal server error has occurred…” message. Nobody likes that. When you use an AuraHandledException you have an opportunity to add some detail back into the response returned to your client-side code. More importantly, you can choose a better message to show your users.

Here’s an example of creating and throwing an AuraHandledException in response to bad input. However, the real benefit of using AuraHandledException comes when you use it in response to a system exception. For example, throw an AuraHandledException in response to catching a DML exception, instead of allowing the DML exception to propagate to your client component code.

This JavaScript controller code handles the AuraHandledException thrown by the Apex controller.

When an Apex controller throws an AuraHandledException, the response state in the JavaScript controller is set to ERROR and you can get the error message by processing response.getError().

This example simply logs the error to the console. To display an error prompt in the UI, use the lightning:notificationsLibrary component.