---
title: Error handling
description: >-
  You can use standard web techniques to handle errors in [checkout UI
  extensions](/api/checkout-ui-extensions/) but you may need to account for how
  they run inside of a [Web
  Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
api_version: 2025-07
api_name: checkout-ui-extensions
source_url:
  html: 'https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/error-handling'
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/error-handling.md
---

# Error handling

You can use standard web techniques to handle errors in [checkout UI extensions](https://shopify.dev/api/checkout-ui-extensions/) but you may need to account for how they run inside of a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).

***

## Handling any error

Add an `unhandledrejection` listener for promise rejections or an `error` listener for other exceptions like Javascript runtime errors or failures to load a resource.

### Examples

* #### Handling any error

  ##### Default

  ```ts
  // For unhandled promise rejections
  self.addEventListener(
    'unhandledrejection',
    (error) => {
      console.warn(
        'event unhandledrejection',
        error,
      );
    },
  );

  // For other exceptions
  self.addEventListener('error', (error) => {
    console.warn('event error', error);
  });
  ```

## Third party libraries

You can use error reporting libraries like [Bugsnag](https://www.bugsnag.com/) or [Sentry](https://sentry.io/). However, they might require extra configuration because UI extensions run inside of a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API). You should also consider using [source maps](https://shopify.dev/docs/apps/build/checkout/test-checkout-ui-extensions#troubleshooting-with-source-maps) to help debug errors.

Tip

You must request [network access](https://shopify.dev/api/checkout-ui-extensions/configuration#network-access) to transmit errors to a third party service.

## Sentry (recommended)

Initialize Sentry following their [Web Worker guide](https://docs.sentry.io/platforms/javascript/configuration/webworkers/). We recommend disabling the default integrations to be sure it will run within a Web Worker. You'll need to add event listeners manually.

If you are writing your UI extension in React, you can follow Sentry's [React integration guide](https://docs.sentry.io/platforms/javascript/guides/react/) to get additional context on errors thrown while rendering your components. Integrations like tracing do not currently run in Web Workers ([issue](https://github.com/getsentry/sentry-javascript/issues/5289)).

### Examples

* #### Sentry

  ##### Default

  ```ts
  import {
    reactExtension,
    Banner,
  } from '@shopify/ui-extensions-react/checkout';
  import * as Sentry from '@sentry/browser';

  Sentry.init({
    dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
    defaultIntegrations: false,
  });

  self.addEventListener(
    'unhandledrejection',
    (error) => {
      Sentry.captureException(
        new Error(error.reason.stack),
      );
    },
  );

  self.addEventListener('error', (error) => {
    Sentry.captureException(
      new Error(error.reason.stack),
    );
  });

  // Your normal extension code.
  export default reactExtension(
    'purchase.checkout.block.render',
    () => <Extension />,
  );

  function Extension() {
    return <Banner>Your extension</Banner>;
  }
  ```

## Bugsnag

Follow [Bugsnag's documentation](https://docs.bugsnag.com/platforms/javascript/) to install it for your extension. Bugsnag adds event listeners by default so there's no need to add them manually.

If you use the [CDN version](https://docs.bugsnag.com/platforms/javascript/cdn-guide/), you'll need to add polyfill code (see example) before importing Bugsnag because it tries to access some variables that are not available in Web Workers ([details](https://github.com/bugsnag/bugsnag-js/issues/1506)).

If you are writing your UI extension in React, you can follow Bugsnag's [React integration guide](https://docs.bugsnag.com/platforms/javascript/legacy/react/) to get additional context on errors thrown while rendering your components.

### Examples

* #### Bugsnag

  ##### Default

  ```ts
  /**
   * The CDN version of Bugsnag requires this polyfill.
   */
  (() => {
    const document = {
      documentElement: {
        outerHTML: '',
        createElement: () => ({}),
        clientWidth: 0,
        clientHeight: 0,
      },
      addEventListener: () => {},
    };
    const history = {};
    const window = self;
    self.window = window;
    window.document = document;
    window.history = history;
  })();
  ```