Throwing and Handling Errors

The framework gives you flexibility in handling unrecoverable and recoverable app errors in JavaScript code. For example, you can throw these errors in a callback when handling an error in a server-side response.

Unrecoverable Errors

Don’t depend on the internals of a Lightning base component for error handling as its internals can change in future releases. Errors that are recoverable can change into unrecoverable errors and vice versa. If you encounter an unexpected error, you can sometimes get more information by enabling debug mode.

Note

Use throw new Error("error message here") for unrecoverable errors, such as an error that prevents your app from starting successfully. The error message is displayed.

$A.error() is deprecated. Throw the native JavaScript Error object instead by using throw new Error().

Note

This example shows you the basics of throwing an unrecoverable error in a JavaScript controller.

<!--c:unrecoverableError-->
<aura:component>
    <lightning:button label="throw error" onclick="{!c.throwError}"/>
</aura:component>

Here is the client-side controller source.

/*unrecoverableErrorController.js*/
({
    throwError : function(component, event){
        throw new Error("I can’t go on. This is the end.");
    }
})

Recoverable Errors

To handle recoverable errors, use a component, such as ui:message, to tell users about the problem.

This sample shows you the basics of throwing and catching a recoverable error in a JavaScript controller.

<!--c:recoverableError-->
<aura:component>
    <p>Click the button to trigger the controller to throw an error.</p>
    <div aura:id="div1"></div>

    <lightning:button label="Throw an Error" onclick="{!c.throwErrorForKicks}"/>
</aura:component>

Here is the client-side controller source.

/*recoverableErrorController.js*/
({
    throwErrorForKicks: function(cmp) {
        // this sample always throws an error to demo try/catch
        var hasPerm = false;
        try {
            if (!hasPerm) {
                throw new Error("You don't have permission to edit this record.");
            }
        }
        catch (e) {
            $A.createComponents([
                ["ui:message",{
                    "title" : "Sample Thrown Error",
                    "severity" : "error",
                }],
                ["lightning:formattedText",{
                    "value" : e.message
                }]
                ],
                function(components, status, errorMessage){
                    if (status === "SUCCESS") {
                        var message = components[0];
                        var outputText = components[1];
                        // set the body of the ui:message to be the ui:outputText
                        message.set("v.body", outputText);
                        var div1 = cmp.find("div1");
                        // Replace div body with the dynamic component
                        div1.set("v.body", message);
                    }
                    else if (status === "INCOMPLETE") {
                        console.log("No response from server or client is offline.")
                        // Show offline error
                    }
                    else if (status === "ERROR") {
                        console.log("Error: " + errorMessage);
                        // Show error message
                    }
                }
            );
        }
    }
})

The controller code always throws an error and catches it in this example. The message in the error is displayed to the user in a dynamically created ui:message component. The body of the ui:message is a ui:outputText component containing the error text.