Difference Between Throwing AuraHandledException and Custom Exception in Apex Aura-Enabled Methods

Question

In Salesforce documentation, it is mentioned that Aura-enabled Apex methods should 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:

public class CustomException extends Exception {
}

If I use this custom exception in my code:

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

And compare it with:

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

My Observations :

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 custom error message that was provided when the exception was thrown (e.g., "Something went wrong").

My Question:

What are the key differences in behaviour when using these two types of exceptions in an Aura-enabled Apex method?

I would appreciate examples or explanations regarding the use cases for each approach.

Answer 1

One thing to be aware is that if you have a test method that checks the exception's message in an assert, you need to do the following in the code-under-test

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

If you do

throw new AuraHandledException(myMessage);

and in the test method you catch the error, this assert will fail

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

Reference

Answer 2

They provide same behaviour but AuraHandledException is preferred to use in client side and custom exception is used for specific use cases.

AuraHandledException ensures a user-friendly error message to the client. It is the mostly preferred the error needs to be displayed to the user. And salesforce does the handling for this.

Advised to use: When you need a user-friendly error message to be displayed to the client.

CustomException the client-side catch block may receive a less user-friendly or generic error message, depending on how Salesforce decides to serialize the CustomException.

Advised to use: Use for internal exception handling, business logic, or non-client-facing errors. Let's say you have a object named Object A and is used in apex in many places so using a custom exception for this will be easier to identify for devs too that this exception is related to some issues in Object A.