Handle Errors in Lightning Data Service

Lightning Data Service (LDS) wire adapters return an error when a resource, such as a record or an object, is inaccessible on the server.

For example, an error occurs if you pass in an invalid input to the wire adapter, such as an invalid record Id or missing required fields. An error is also returned if the record isn’t in the cache and the server is offline. Also, a resource can become inaccessible on the server when it’s deleted or has its sharing or visibility settings updated.

LWC Error Handling Best Practices

Using the LDS wire adapters means you are working with asynchronous JavaScript, which is similar to promises. To handle errors, you typically use a try-catch block. However, the try-catch block can handle exceptions in synchronous code only. So only errors within a single transaction are caught by a try-catch block.

Consider this asynchronous code.

The code prints first, then runs setTimeOut(), and prints third in a single transaction. The callback function is called 1 second later, as specified by the timeout delay. However, second isn't printed since it's not part of the first transaction.

To ensure that your error in asynchronous code is handled correctly in a try-catch block, use the try-catch block inside the callback function.

The code prints first, then runs setTimeOut(), and prints third in a single transaction. When the callback is called 1 second later, the try-catch block handles the error and prints error correctly.

When you specify the @wire decorator and make a call out to a wire service, the wire service calls the wire adapter to fetch the data. The wire adapter fetches the data either from Salesforce servers or the LDS cache, if it's available. The wire adapter then returns the data back to the service, which provisions the data back to your component.

We say "provisions" instead of "requests" or "fetches" because a network request isn't involved if the data exists in the client cache.

The response may throw an error during or after value provisioning. For example, the wire adapter tries to fetch the data from your Apex method and the Apex method throws an exception. This exception can occur because of a number of reasons, such as if you don't parse a required parameter or if there's an issue fetching from the cache.

If the value provisioning is successful, you can also encounter an error while handling the response on your component.

The lwc-recipes repo has many wire service examples. Look for components that start with lds*, such as ldsCreateRecord, or components that start with apex*, such as apexImperativeMethod.

When you wire a method to a function or a property, the error property stores the error during value provisioning. We recommend that you include the else if block to handle errors on your wire functions. Wire a method to a function with error handling like this.

If you wire a method to a property instead, you can handle the error by checking the yourPropertyName.error value.

You must use the data and error properties as they are hardcoded values in the API. See Wire Service Syntax.

The FetchResponse error object is modeled after the Fetch API’s Response object. It contains the body of the response and a status code and message.

Here's an example error response when you provide an incorrect recordId for an object.

The error response includes these properties.

  • body (Object or Array)—The body of the response, which is defined by the underlying API.
  • ok (Boolean)—Specifies whether the response was successful or not. For an error, ok is always false and contains a status in the range 400–599.
  • status (Number)—Contains the status code of the response, for example, 404 if a resource is not found or 500 for an internal server error.
  • statusText (String)—Contains the status message corresponding to the status code, for example, NOT_FOUND for a status code of 404.

To handle errors returned by the getRecord wire adapter, you can display the error in your HTML template or handle them in JavaScript only. This example displays the error to users.

The JavaScript code checks if the error body is an array or object and returns the error message.

The lwc-recipes repo has an ldsUtils example that reduces one or more LDS errors into a string array of error messages.

The body of the error response depends on the API that returns it.

  • UI API read operations, such as the getRecord wire adapter, return error.body as an array of objects.
  • UI API write operations, such as the createRecord wire adapter, return error.body as an object, often with object-level and field-level errors.
  • Apex read and write operations return error.body as an object.
  • Network errors, such as an offline error, return error.body as an object.

See Also