React Error Boundary
Learn how the React Native SDK exports an error boundary component that leverages React component APIs.
The React Native SDK exports an error boundary component that uses React component APIs to automatically catch and send JavaScript errors from inside a React component tree to Sentry.
To use the Error Boundary component, you need to have the React Native SDK installed and configured for error monitoring.
import React from "react";
import * as Sentry from "@sentry/react-native";
<Sentry.ErrorBoundary fallback={<p>An error has occurred</p>}>
<Example />
</Sentry.ErrorBoundary>;
The Sentry Error Boundary is also available as a higher-order component.
import React from "react";
import * as Sentry from "@sentry/react-native";
Sentry.withErrorBoundary(Example, {
fallback: <p>an error has occurred</p>,
});
Note
In development mode, React will rethrow errors caught within an error boundary to the global error handler. This will result in Sentry only reporting an error from the global error handler, but not from the error boundary itself. We recommend testing the error boundary with a production build of React.
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.
import React from "react";
import * as Sentry from "@sentry/react-native";
import { Example } from "../example";
function FallbackComponent() {
return <div>An error has occurred</div>;
}
const myFallback = <FallbackComponent />;
// Alternatively:
// const myFallback = () => <FallbackComponent />;
class App extends React.Component {
render() {
return (
<Sentry.ErrorBoundary fallback={myFallback} showDialog>
<Example />
</Sentry.ErrorBoundary>
);
}
}
export default App;
Note
By default, React logs all errors to the console, even if you're using a React error boundary. If you're using the CaptureConsole integration, Sentry will capture the error there and not through the error boundary.
In React v17 and above, the SDK will automatically parse the error boundary componentStack and attach the full stacktrace to the event via error.cause. This requires the nativeLinkedErrorsIntegration to be enabled. (It's enabled by default.) To get the full source context, we recommend setting up source maps for your project.
The ErrorBoundary component exposes a variety of props that can be passed in for extra configuration. There aren't any required options, but we highly recommend setting a fallback component.
fallback (React.ReactNode or Function)
A React element to render when the error boundary catches an error. This can be an actual React element (for example, <Fallback />), or a function that returns a React element. If you provide a function, Sentry will call it with additional info and helpers (see example below).
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().
beforeCapture (Function)
A function that gets called before an error is sent to Sentry, allowing for extra tags or context to be added to the error.
Below, is an example where a fallback prop, using the render props approach, is used to display a fallback UI on error. The fallback UI returns to a standard component state when reset using the resetError() API, provided by the component through render props.
import React from "react";
import { Button, Text } from "react-native";
import * as Sentry from "@sentry/react-native";
class MyComponent extends React.Component {
constructor(props) {
super(props);
this.state = {
message: "This is my app",
};
}
render() {
return (
<Sentry.ErrorBoundary
fallback={({ error, componentStack, resetError }) => (
<React.Fragment>
<Text>You have encountered an error</Text>
<Text>{error.toString()}</Text>
<Text>{componentStack}</Text>
<Button
title="Click here to reset!"
onPress={() => {
this.setState({ message: "This is my app" });
// When resetError() is called it will
// remove the Fallback component and render
// the Sentry ErrorBoundary's children
// in their initial state
resetError();
}}
/>
</React.Fragment>
)}
>
<Text>{this.state.message}</Text>
{/* 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
title="Click here to change message!"
onPress={() =>
this.setState({ message: { text: "Hello World" } })
}
/>
</Sentry.ErrorBoundary>
);
}
}
export default MyComponent;
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:
import React from "react";
import { View, Text } from "react-native";
import * as Sentry from "@sentry/react-native";
function MyComponent({ props }) {
return (
<React.Fragment>
<Sentry.ErrorBoundary
beforeCapture={(scope) => {
scope.setTag("location", "first");
scope.setTag("anotherTag", "anotherValue");
}}
>
<View>
<Text>First</Text>
</View>
</Sentry.ErrorBoundary>
<Sentry.ErrorBoundary
beforeCapture={(scope) => {
scope.setTag("location", "second");
}}
>
<View>
<Text>Second</Text>
</View>
</Sentry.ErrorBoundary>
</React.Fragment>
);
}
export default MyComponent;
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").