Error Handling with Promises

Promises can simplify code that handles the success or failure of asynchronous calls. To use error handling with promises, use the catch() method on the promise that is returned from calling an API method.

The catch() method returns a promise and accepts a single function parameter that’s called if the promise is rejected. This function has one argument that shows the reason for the rejection. The promise returned by catch() is rejected if the function that is passed in either throws an error or returns a promise that’s rejected. Otherwise, the promise is resolved.

Best Practices for Error Handling

When handling errors for Lightning console apps, consider validating the input, logging the error message, and provide user feedback if the method fails. For example, if you use setSelectedNavigationItem(), check that the developer name is valid and handle any errors accordingly.

The example uses console.error and console.log for simplicity. To show an error notification in the UI, use lightning/platformShowToastEvent or lightning/toast instead.

1import { setSelectedNavigationItem } from 'lightning/platformNavigationItemApi';
2
3async safeNavigate(developerName) {
4    // Validate input
5    if (!developerName || typeof developerName !== 'string') {
6        console.error('Invalid developer name provided');
7        return false;
8    }
9
10    try {
11        await setSelectedNavigationItem(developerName);
12        return true;
13    } catch (error) {
14        // Log error details
15        console.error('Navigation failed:', {
16            developerName,
17            error: error.message,
18            stack: error.stack
19        });
20
21        // Show user-friendly message
22        this.dispatchEvent(new CustomEvent('navigationerror', {
23            detail: { message: 'Unable to navigate. Please try again.' }
24        }));
25
26        return false;
27    }
28}

Common Lightning Console Errors

Here are several common errors that you can encounter when working with Lightning Console JavaScript API.

Error: This API is only available in Lightning console apps.

This error is thrown when an API method is called from outside a console app.

1try {
2    await focusNavigationItem();
3} catch (error) {
4    if (error.message.includes('console')) {
5        console.log('Not running in a console app');
6    }
7}

Error: setSelectedNavigationItem requires a valid developerName parameter

This error is thrown when the setSelectedNavigationItem()contains an invalid developer name.

1try {
2    await setSelectedNavigationItem('');
3} catch (error) {
4    console.error('Invalid parameter:', error.message);
5}

Error: Navigation item doesn't exist

This error is thrown when the navigation item isn’t found.

1try {
2    await setSelectedNavigationItem('NonExistentItem');
3} catch (error) {
4    console.error('Navigation item not found:', error);
5}

Error: "The selected navigation item has unsaved changes. Save the changes, then try again.

This error is thrown when you have unsaved changes.

1try {
2    await refreshNavigationItem();
3} catch (error) {
4    if (error.message.includes('unsaved changes')) {
5        console.log('Please save changes before refreshing');
6    }
7}