---
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: 2026-01
api_name: checkout-ui-extensions
source_url:
  html: https://shopify.dev/docs/api/checkout-ui-extensions/latest/error-handling
  md: https://shopify.dev/docs/api/checkout-ui-extensions/latest/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.

## Handling any error

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


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

***

## Third party libraries

You can use error reporting libraries like [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

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

## Sentry

```ts
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {
  BrowserClient,
  captureException,
  defaultStackParser,
  getCurrentScope,
  makeFetchTransport,
} from '@sentry/browser';


const sentryClient = new BrowserClient({
  dsn: 'https://examplePublicKey@o0.ingest.sentry.io/0',
  transport: makeFetchTransport,
  stackParser: defaultStackParser,
  integrations: [],
});
getCurrentScope().setClient(sentryClient);
sentryClient.init();


self.addEventListener('unhandledrejection', (event) => {
  captureException(event.reason);
});


self.addEventListener('error', (event) => {
  captureException(event.error);
});


// Your normal extension code.
export default function extension() {
  render(<Extension />, document.body);
}


function Extension() {
  return <s-banner>Your extension</s-banner>;
}
```

***