Issue

I'm building a Chrome extension and want to capture errors with Sentry. What is the recommended way to integrate Sentry into an extension that runs across background scripts, content scripts, and popup UI?

Applies To

All SaaS Customers and Self-Hosted Users
JavaScript SDK (Browser), version 8.x and above
Browser Extensions / Shared Environments

Resolution

You can use Sentry in a Chrome extension, but do not initialize it with Sentry.init(). A browser extension shares the page with the host website, and calling Sentry.init() pollutes global state, so your extension's events could be sent to the website's Sentry project or vice versa.

Instead, set up a client and scope manually, and avoid integrations that use global state (such as BrowserApiErrors, Breadcrumbs, and GlobalHandlers):

import {
  BrowserClient,
  defaultStackParser,
  getDefaultIntegrations,
  makeFetchTransport,
  Scope,
} from "@sentry/browser";

// Filter out integrations that rely on global state
const integrations = getDefaultIntegrations({}).filter(
  integration =>
    !["BrowserApiErrors", "Breadcrumbs", "GlobalHandlers"].includes(
      integration.name
    )
);

const client = new BrowserClient({
  dsn: "___PUBLIC_DSN___",
  transport: makeFetchTransport,
  stackParser: defaultStackParser,
  integrations,
});

const scope = new Scope();
scope.setClient(client);
client.init();

// Capture errors manually against this scope
scope.captureException(new Error("example"));

Use this pattern in each context where you want to report errors (background, content script, popup).

This manual setup is intended for capturing errors (and logs) in a shared environment. Automatic performance tracing is not recommended in an extension, because the tracing integration instruments global browser APIs (such as history, fetch, and XHR). That is the same global-state behavior you avoid here, and enabling it can interfere with the host page's own Sentry. If you need performance data, create spans manually against your client and scope rather than relying on automatic instrumentation.

If Sentry is not capturing your extension's errors, check that the browser-extension inbound filter is not discarding them, under Settings > Projects > [your project] > Inbound Filters.

For the full setup, including the complete list of integrations to filter and how to send logs, see the shared environments and browser extensions guide.

How do I integrate Sentry with a Chrome extension?

Issue

Applies To

Resolution