React Error Boundary

The React SDK exports an error boundary component that leverages React component APIs to automatically catch and send JavaScript errors from inside a React component tree to Sentry.

Copied
import React from "react";
import * as Sentry from "@sentry/react";

<Sentry.ErrorBoundary fallback={"An error has occurred"}>
  <Example />
</Sentry.ErrorBoundary>;

The Sentry Error Boundary is also available as a higher order component.

Copied
import React from "react";
import * as Sentry from "@sentry/react";

Sentry.withErrorBoundary(Example, { fallback: "an error has occurred" });

In the example below, when the <Example /> component hits an error, the <Sentry.ErrorBoundary> component will send data about that error and the component tree to Sentry, open a user feedback dialog, and render a fallback UI.

Copied
import React from "react";
import * as Sentry from "@sentry/react";

import { Example } from "../example";

function FallbackComponent() {
  return <div>An error has occurred</div>;
}

class App extends React.Component {
  render() {
    return (
      <Sentry.ErrorBoundary fallback={FallbackComponent} showDialog>
        <Example />
      </Sentry.ErrorBoundary>
    );
  }
}

export default App;

Options

The ErrorBoundary component exposes a variety of props that can be passed in for extra configuration. There are no required options, but we highly recommend that you set a fallback component.

showDialog (boolean)
If a Sentry User Feedback Widget should be rendered when the Error Boundary catches an error.

dialogOptions (Object)
Options that are passed into the Sentry User Feedback Widget. See all possible customization options here.

fallback (React.ReactNode or Function)
A fallback component that gets rendered when the error boundary encounters an error. You can can either provide a React Component, or a function that returns a React Component as a valid fallback prop. If you provide a function, Sentry will call the function with the error and the component stack at the time of the error.

onError (Function)
A function that gets called when the Error Boundary encounters an error. onError is useful if you want to propagate the error into a state management library like Redux, or if you want to check any side effects that could have occurred due to the error.

onMount (Function)
A function that gets called on ErrorBoundary componentDidMount().

onUnmount (Function)
A function that gets called on ErrorBoundary componentWillUnmount().

onUnmount (Function)
A function that gets called on ErrorBoundary componentWillUnmount().

beforeCapture (Function)

(New in version 5.20.0)
A function that gets called before an error is sent to Sentry, allowing for extra tags or context to be added to the error.

Examples

Setting a Fallback Function (Render Props)

Below is an example where a fallback prop, using the render props approach, is used to display a fallback UI on error, and gracefully return to a standard component state when reset.

Copied
import React from "react";
import * as Sentry from "@sentry/react";

class App extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      message: "This is my app",
    };
  }

  render() {
    return (
      <Sentry.ErrorBoundary
        fallback={({ error, componentStack, resetError }) => (
          <React.Fragment>
            <div>You have encountered an error</div>
            <div>{error.toString()}</div>
            <div>{componentStack}</div>
            <button
              onClick={() => {
                this.setState({ message: "This is my app" });
                resetError();
              }}
            >
              Click here to reset!
            </button>
          </React.Fragment>
        )}
      >
        <div>{this.state.message}</div>
        {/* on click, this button sets an Object as a message, not a string. */}
        {/* which will cause an error to occur in the component tree */}
        <button
          onClick={() => this.setState({ message: { text: "Hello World" } })}
        >
          Click here to change message!
        </button>
      </Sentry.ErrorBoundary>
    );
  }
}

export default App;

Using multiple error boundaries

(New in version 5.20.0)

When using multiple error boundaries, we recommend using beforeCapture to set tags/context so that you can tell which error boundary the error occurred from. In the example below, we attach tags to errors based on what route they rendered in.

Copied
import React from 'react';
import * as Sentry from '@sentry/react';

function App({ props }) {
  return (
    <ErrorBoundary
        beforeCapture={(scope) => {
          scope.setTag("location", "first");
          scope.setTag("anotherTag", "anotherValue");
        }}
      >
        <Route to="path/to/first" component={First} />
      </ErrorBoundary>
      <ErrorBoundary
        beforeCapture={(scope) => {
          scope.setTag("location", "second");
        }}
      >
        <Route to="path/to/second" component={Second} />
      </ErrorBoundary>
  )
}

export default App;

Next Steps:

You can edit this page on GitHub.