Show a recovery interface for a failed React subtree and send rendering errors to Sentry. Learn what a boundary catches, how to test it and what needs separate handling.
An error boundary provides a fallback for rendering failures in part of a React tree. Sentry’s React boundary also reports the captured error. Put boundaries around sections that can recover independently, such as a preview or dashboard panel, so the surrounding interface can remain usable.
What it catches
A boundary catches errors thrown while React renders its descendants and during relevant lifecycle work. It does not generally catch errors in event handlers, arbitrary asynchronous callbacks, server rendering or the boundary’s own fallback. React has specific handling for errors inside transitions; check the documentation for your React version.
1. Initialize Sentry once
This example targets a client-rendered Vite application using React 19 and @sentry/react 11.12.0. Add the SDK and use your project’s DSN. Framework-managed applications such as Next.js have their own Sentry setup and error handling; do not replace their bootstrap with this file.
npm install @sentry/react@11.12.0VITE_SENTRY_DSN=your-project-dsnimport { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import * as Sentry from '@sentry/react';
import { App } from './App';
Sentry.init({
dsn: import.meta.env.VITE_SENTRY_DSN,
dataCollection: {
userInfo: false, cookies: false, httpHeaders: false,
httpBodies: [], urlQueryParams: false,
genAI: { inputs: false, outputs: false }
}
});
const element = document.getElementById('root');
if (!element) throw new Error('Missing root element');
createRoot(element).render(<StrictMode><App /></StrictMode>);A browser DSN identifies the destination project and is included in the built application. It is not a private authentication token. Keep Sentry auth tokens server-side, and review the event data and SDK integrations enabled for the product. In SDK 11, dataCollection replaces sendDefaultPii. The example disables several automatic data categories, but that does not scrub sensitive text your application puts in an error or manually attaches to an event.
2. Wrap a section with a useful fallback
The button below triggers a render failure deliberately. Reset clears both the boundary and the state causing the failure; simply retrying the same broken state would throw again.
import { useState } from 'react';
import * as Sentry from '@sentry/react';
function Preview({ fail }: { fail: boolean }) {
if (fail) throw new Error('Intentional boundary test');
return <p>The preview is working.</p>;
}
export function App() {
const [fail, setFail] = useState(false);
return (
<main>
<h1>Preview</h1>
<Sentry.ErrorBoundary
beforeCapture={scope => scope.setTag('section', 'preview')}
onReset={() => setFail(false)}
fallback={({ resetError }) => (
<section role="alert">
<p>The preview could not be displayed.</p>
<button onClick={resetError}>Try again</button>
</section>
)}
>
<Preview fail={fail} />
</Sentry.ErrorBoundary>
<button onClick={() => setFail(true)}>Test rendering failure</button>
</main>
);
}3. Verify reporting and recovery
- Use a development or test Sentry project with a valid DSN.
- Click Test rendering failure and confirm the preview is replaced by the fallback while the heading and controls remain.
- Click Try again and confirm the preview returns.
- Inspect the event in Sentry, including the section tag and stack trace. Configure source maps through your build workflow for readable production stacks.
- Repeat with a production build. Development mode and SDK integrations can affect duplicate-looking console reports.
Handle other failures where they occur
For a failed request, catch the error in the request or event handler, show a useful message and explicitly report it when appropriate. A boundary is not a replacement for loading states, validation, retries or logging on the server. Avoid sending credentials, request bodies or personal data as error context.
React 19 also exposes root error-reporting hooks. Sentry documents how to connect those hooks and use boundaries for local fallback interfaces. Decide where errors are reported before adding manual capture calls; reporting the same failure through several paths can create duplicate events.
Documentation and references
Working with React and Error boundary? Tell us what you're building and our engineers will tell you how they would approach it.
Talk to our team →