AuraHandledException vs Custom Exception: Key Differences

Question

In Salesforce documentation, it is recommended that Aura-enabled Apex methods throw an AuraHandledException to propagate user-friendly error messages to the client. However, I have a custom exception class in my codebase, and I’m curious about the differences in behavior when throwing a custom exception versus an AuraHandledException.

For example, if I define a custom exception class:

public class CustomException extends Exception {
}

And throw it in my code like this:

throw new CustomException('Something went wrong.');

Compared to throwing an AuraHandledException:

throw new AuraHandledException('Something went wrong.');

On the client side, the error body appeared similar in both cases. However, I noticed a difference in the Apex Debug Logs:

For AuraHandledException, the Status column in the debug logs displayed "Script-thrown exception."For CustomException, the Status column displayed the actual error message, such as "Something went wrong."

What are the key differences in behavior when using these two types of exceptions in an Aura-enabled Apex method? When should each approach be used?

Answer

The main difference between AuraHandledException and a custom exception in Aura-enabled methods is how Salesforce processes and logs them. While both return similar error responses to the client, AuraHandledException is specifically designed for user-friendly messages. In debug logs, it shows "Script-thrown exception", whereas a custom exception logs the actual error message. Using AuraHandledException is recommended for better handling in Lightning components.

CRS Info Solutions offers expert Salesforce online training with real-time projects, certification guidance, interview coaching, and a job-ready approach. Enroll for free demo today!!!

1. Client-Side Handling

When an exception is thrown from an Aura-enabled Apex method, it is sent to the client-side JavaScript controller in the Lightning component. Both AuraHandledException and custom exceptions return error responses, but Salesforce recommends AuraHandledException because it is specifically designed for user-friendly error messages. Custom exceptions may still propagate, but their handling can be less predictable. Proper error handling in JavaScript ensures a smooth user experience by displaying meaningful messages instead of generic errors.

2. Debug Logs Behavior

When an AuraHandledException is thrown, the Status column in the debug logs displays "Script-thrown exception", making it less informative for debugging. In contrast, a custom exception logs the exact error message, such as "Something went wrong", which can be more useful for identifying issues. This difference matters when troubleshooting, as AuraHandledException does not reveal the actual message in logs. Developers should consider this when deciding which exception type to use, especially if detailed logging is necessary.

3. Test Class Consideration

When writing test classes for Aura-enabled methods, handling AuraHandledException requires special attention. Directly passing a message in the constructor does not always retain it when retrieved in a test. To ensure assertions on error messages pass, always use setMessage() before throwing the exception.

String myMessage = 'some message';
AuraHandledException e = new AuraHandledException(myMessage);
e.setMessage(myMessage);
throw e;

If you only use:

throw new AuraHandledException(myMessage);

Then in a test method:

try {
    myCodeUnderTest.doSomething();
} catch (AuraHandledException e) {
    Assert.areEqual('some message', e.getMessage(), 'msg should be as expected');
}

The assertion may fail because getMessage() does not always return the expected message unless explicitly set using setMessage().

4. When to Use Which?

• Use AuraHandledException when you need to return a controlled, user-friendly message to the client and conform to Salesforce best practices for Aura components.
  
• Use a custom exception when you need additional exception handling logic or differentiation between various error types in your Apex code. However, custom exceptions may not always propagate cleanly to the client.

Summing Up

For Aura-enabled Apex methods, AuraHandledException is the preferred way to propagate user-friendly error messages to the client, ensuring proper handling in Lightning components. While custom exceptions log messages directly and allow for additional handling, they do not integrate as cleanly with Aura’s error-handling mechanisms. Additionally, when testing AuraHandledException, always use setMessage() to ensure the expected message is retained in assertions.

Empower Your Career with Salesforce Training in India

Elevate your professional journey with CRS Info Solutions’ top-rated salesforce training, crafted to provide the skills and expertise required to excel in the ever-evolving Salesforce ecosystem. Our industry-focused courses span Salesforce Admin, Developer, and AI modules, blending in-depth theoretical knowledge with hands-on experience through practical, real-world projects. Whether you’re new to Salesforce or a seasoned professional, our well-structured program ensures you master the tools and techniques needed to stand out.

With a strong emphasis on practical application, Salesforce training in India we offer personalized mentorship, detailed study resources, and expert-led certification preparation to fully equip you for success in interviews and beyond. Gain the confidence and skills to thrive in your Salesforce career.

Don’t wait—join our free demo class today and take the first step toward a rewarding future! Enroll now for a free demo!!

Related Posts :

• What is a Map class in Salesforce Apex? with examples
  
• What are classes in Apex programming?