Work with Errors
You can encounter different error types when working with Lightning Web Components (LWC). Learn about different error types, how the errors are propagated, and how you can handle the errors.
The most common errors you encounter with LWC are JavaScript errors, Lightning Data Service errors, and Apex errors.
LWC uses the standard Error JavaScript object for runtime errors, which returns error type names like ReferenceError, SyntaxError, and so on. Throw exceptions using throw and handle them using the try-catch block.
For example, you get a ReferenceError in this case.
JavaScript errors can be thrown in synchronous or asynchronous code. Synchronous code is run line by line like this.
When an error is thrown, any code that follows the error fails to run.
Lightning Data Service (LDS) manages data for you via wire adapters like those in the lightning/ui*Api modules. You're working with asynchronous code when you write code that calls wire service or JavaScript promises. See Handle Errors in Lightning Data Service.
Retrieving data using Apex means you can encounter errors or exceptions from your Apex code. When your Apex code encounters an error, you can use a try-catch block and handle the error in Apex. Otherwise, the error becomes unhandled and gets thrown directly to the client. You can handle a built-in Apex exception or create your own custom exception. See Handle Errors from Apex.
When your code throws an error but don't handle it, the error gets thrown to the parent component. If the parent component doesn't handle the error either, the error is then thrown to the enclosing app such as Lightning Experience or the Experience Builder site. You'll see a popup titled "A Component Error has occurred!" or "Something went wrong" with the error message and stack trace. Alternatively, you can handle the error more elegantly using a try-catch block.
Errors from asynchronous code are handled slightly differently. If the component doesn't handle the error, it gets thrown to the parent component. If the parent component doesn't handle the error, it gets thrown directly to the browser in the console.
This example shows how errors are propagated when working with synchronous vs asynchronous code.
In the synchronous example, the error is thrown by the enclosing app in Lightning Experience or the Experience Builder site. In the asynchronous example, the error is thrown in the browser console.
Depending on how you want to handle errors, you can choose to display the errors on the user interface. To help users rectify the errors effectively, include a helpful message that briefly explains a corrective action. You can usually surface a helpful message from LDS or Apex or provide your own. Displaying errors consistently across the app is also helpful so users can know what to expect.
lwc-recipes is an app that displays errors consistently using the errorPanel component while processing different errors structures using the ldsUtils module.
As discussed in the previous sections, unhandled errors are propagated to the enclosing app or the browser by default. You can throw a custom error, which can be propagated by using the throw keyword or using a custom event. You can also use Lightning Message Service or the pubsub module.
Generally, you want to propagate errors from child components and then handle errors in parent components.
As discussed in Display Errors, you can surface a helpful message from LDS or Apex or provide your own. A common way to display an error is to use a toast. This example displays a custom error on a toast notification using the throw keyword. It uses the ldsUtils module from the lwc-recipes repo to reduce the errors into a string of error messages.
Alternatively, you can display the error provided by LDS or Apex.
The lwc-recipes repo displays errors from LDS on a toast notification. Look for examples that start with lds*, such as ldsCreateRecord.
Using a custom event is helpful when you're working with multiple child components that need to be handled by a parent component in a consistent way. A child component dispatches the custom event and a parent component handles it.
Let's say your child component has a useCustomEvent() function that dispatches a custom event.
The custom event name is error. In the parent component, handle the custom error using the onerror event handler name.
THe parent component displays an alert with the error details.
See Also