Custom Error Messages in Salesforce Lightning

November 3, 2017 Appirio

By Nitin Goyal

Visualforce pages have built-in implementation for showing custom error messages using the page as a medium. Here, we can easily show custom error screens with different text and levels of severity (info/error/warning) regardless of the return type of the apex controller method.

With Lightning components, we don’t have the flexibility to use page messages, and this makes the process more difficult. We have to return an error message for an apex controller method of which the return type is anything other than string (e.g., an apex method that returns a list of sObject).

To show custom error messages in Lightning:

  1. Return the custom error messages from apex method.
  2. Show the error messages in the Component.

Returning the custom error messages from apex method:

The recommended approach is to create — and throw — a System.AuraHandledException from your server-side controller to return a custom error message.

This can be done using the following syntax:

In the apex controller class:
//If Account ID sent as parameter is null
string errAccId = ‘Account ID not available.’;
AuraHandledException ex = new AuraHandledException(errAccId);
throw ex;

Here setMessage() on exception object is important, in order to validate this scenario apply Test Class using the following syntax:

//To validate the scenario in test class
try {

     Controller.Method(”); //calling the controller method with account Id

} catch (AuraHandledException e) {

      System.assert(e.getMessage().contains(‘Account ID not available.’));


Showing the error messages in the Component.

To show the error message on the lightning component UI, we would use the following:

Generic reusable message component:
<aura:component access=”global”>
<aura:attribute name=”message” description=”Message content, can be HTML”

                   type=”String” default=”Message from MessageComponent.cmp”/>
<aura:attribute name=”type”

                   description=”Message type, can be error/warning/info/success”

                   type=”String” default=”info”/>
<div class=”{!’slds-box slds-theme–alert-texture slds-theme–‘ + v.type}”>
<lightning:icon iconName=”{! ‘utility:’+ v.type }” size=”medium”

                       alternativeText=”{!v.type}” Class=”iconContainer”/>&nbsp;
<span class=”slds-text-body–regular”>
<aura:unescapedHtml value=”{!v.message}”/>

In the controller/helper:

action.setCallback(this, function(resp) {
if (resp.getState() === “SUCCESS”) {

     component.set(“v.messageType”, ‘success’ );
component.set(“v.message”, ‘Completed Successfully!’ );
else if (resp.getState() === “ERROR”) {

     component.set(“v.messageType”, ‘error’ );
var errors = resp.getError();
if (errors) {
if (errors[0] && errors[0].message) {
component.set(“v.message”,errors[0].message );//Fetching Custom Message.
else {
component.set(“v.message”, ‘Request Failed!’ );

Using the message component in our component markup:

<c:MessageComponent type=”{!v.messageType}” message=”{!v.message}” />


For error message would look like:

<c:MessageComponent type=”error” message=”Account Id Not available.” />


                    Similar to a warning message, information and success screens could look like:

This implementation helps us achieve our goal of custom error messages from apex controller to our Lightning component, and is also reusable, as we have a generic MessageComponent that can be utilized for all similar use cases.

Interested in learning more about the technology side of Appirio? Check out the rest of our Tech Blog.


Previous Article
Expanding Your IoT Explorer Prototype
Expanding Your IoT Explorer Prototype

By Dave Stanton In a previous blog, we created a base IoT Explorer orchestration, and spent some time discu...

Next Article
Worker Experience for Retail - Interactive
Worker Experience for Retail - Interactive

Today’s retail workers expect a consumer-grade experience from the moment they are recruited, and on throug...