Instrument Error Tracking

AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

React Native Error Tracking installation

Canonical URL: https://posthog.com/docs/error-tracking/installation/react-native

Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use https://eu.i.posthog.com instead of https://us.i.posthog.com (ingestion host), and use https://eu.posthog.com instead of https://app.posthog.com (app host for links).

On this page

• Install with the wizard

• Install the package

• Configure PostHog

• Send events

• Set up exception autocapture

• Set up error boundaries

• Manually capture exceptions

• Future features

• Verify error tracking

• Upload source maps & native symbols

• iOS dependency resolution for native crash capture

Install with the wizard

Run this command in your project directory to add PostHog to your React Native project. The wizard detects your framework, installs the SDK, and sets up your first events.

npx @posthog/wizard

Or set it up manually by following the rest of this guide.

1. 1

   Install the package

   Required

   Install the PostHog React Native library and its dependencies:

   Expo

   Copy

   npx expo install posthog-react-native expo-file-system expo-application expo-device expo-localization

   yarn

   Copy

   yarn add posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize
   
   # for iOS
   cd ios && pod install

   npm

   Copy

   npm i -s posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize
   
   # for iOS
   cd ios && pod install

2. 2

   Configure PostHog

   Required

   PostHog is most easily used via the PostHogProvider component. Wrap your app with the provider:

   App.tsx

   Copy

   import { PostHogProvider } from 'posthog-react-native'
   
   export function MyApp() {
       return (
           <PostHogProvider
               apiKey="<ph_project_token>"
               options={{
                   host: "https://us.i.posthog.com",
               }}
           >
               <RestOfApp />
           </PostHogProvider>
       )
   }

3. 3

   Send events

   Recommended

   Once installed, PostHog will automatically start capturing events. You can also manually send events using the usePostHog hook:

   Component.tsx

   Copy

   import { usePostHog } from 'posthog-react-native'
   
   function MyComponent() {
       const posthog = usePostHog()
   
       const handlePress = () => {
           posthog.capture('button_pressed', {
               button_name: 'signup'
           })
       }
   
       return <Button onPress={handlePress} title="Sign Up" />
   }

4. 4

   Set up exception autocapture

   Recommended

   Client-side configuration only

   Support for remote configuration in the error tracking settings requires SDK version 4.35.0 or higher.

   You can autocapture exceptions by configuring the errorTracking when setting up PostHog:

   React Native

   Copy

   export const posthog = new PostHog('<ph_project_token>', {
     errorTracking: {
       autocapture: {
         uncaughtExceptions: true,
         unhandledRejections: true,
         console: ['error', 'warn'],
         nativeCrashes: true, // native iOS/Android crashes (see below)
       },
     },
   })

   Configuration options:

   Option	Description
   uncaughtExceptions	Captures Uncaught exceptions (ReactNativeGlobal.ErrorUtils.setGlobalHandler)
   unhandledRejections	Captures Unhandled rejections (ReactNativeGlobal.onunhandledrejection)
   console	Captures console logs as errors according to the reported LogLevel
   nativeCrashes	Captures native iOS/Android crashes. Requires @posthog/react-native-plugin and uploaded native symbols (see below)

   Capturing native crashes

   nativeCrashes captures native iOS and Android crashes that the JavaScript layer can't see. Beyond the config above, it needs:

   1. The optional native plugin installed — npx expo install @posthog/react-native-plugin (Expo) or npm i @posthog/react-native-plugin (bare React Native). If it's missing, native capture is a no-op and your JS-level autocapture is unaffected.

   2. Your project's Enable exception autocapture setting enabled in error tracking settings — the same server-side setting that gates JavaScript autocapture.

   3. Native debug symbols uploaded at build time, so crash stack traces are readable. See native crash symbolication.

5. 5

   Set up error boundaries

   Optional

   You can use the PostHogErrorBoundary component to capture rendering errors thrown by components:

   React Native

   Copy

   import { PostHogProvider, PostHogErrorBoundary } from 'posthog-react-native'
   import { View, Text } from 'react-native'
   
   const App = () => {
     return (
       <PostHogProvider apiKey="<ph_project_token>">
         <PostHogErrorBoundary
           fallback={YourFallbackComponent}
           additionalProperties={{ screen: "home" }}
         >
           <YourApp />
         </PostHogErrorBoundary>
       </PostHogProvider>
     )
   }
   
   const YourFallbackComponent = ({ error, componentStack }) => {
     return (
       <View>
         <Text>Something went wrong!</Text>
         <Text>{error instanceof Error ? error.message : String(error)}</Text>
       </View>
     )
   }

   Duplicate errors with console capture

   If you have both PostHogErrorBoundary and console capture enabled in your errorTracking config, render errors will be captured twice. This is because React logs all errors to the console by default. To avoid this, set console: [] on errorTracking.autocapture (for example, errorTracking: { autocapture: { console: [] } }) when using PostHogErrorBoundary.

   Dev mode behavior

   In development mode, React propagates all errors to the global error handler even when they are caught by an error boundary. This means you may see errors reported twice in dev builds. This is expected React behavior and does not occur in production builds.

6. 6

   Manually capture exceptions

   Optional

   You can manually capture exceptions using the captureException method:

   React Native

   Copy

   try {
     // Your awesome code that may throw
     someRiskyOperation();
   } catch (error) {
     posthog.captureException(error)
   }

   This is helpful if you've built your own error handling logic or want to capture exceptions that are handled by your application code.

7. 7

   Future features

   Optional

   We currently don't support the following features:

   • No automatic source map uploads on React Native web

   This will be added in a future release. We recommend you stay up to date with the latest version of the PostHog React Native SDK.

8. Verify error tracking

   Recommended

   Confirm events are being sent to PostHog

   Before proceeding, let's make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.

   Image: Activity feed with events

   Check for exceptions in PostHog

9. 8

   Upload source maps & native symbols

   Required

   Great, you're capturing exceptions! The next step is to upload source maps (for JavaScript stack traces) and native symbols (for native iOS/Android crash symbolication) so PostHog can generate accurate stack traces.

   Let's continue to the next section.

   Upload source maps & native symbols

iOS dependency resolution for native crash capture

CocoaPods is becoming read-only. CocoaPods has announced the following schedule for its public specs repository:

• November 2–6, 2026: A read-only dry run will prevent us from publishing new PostHog iOS SDK versions to CocoaPods.

• December 2, 2026 onward: The repository will be permanently read-only. New PostHog iOS SDK versions will only be available through Swift Package Manager (SPM).

Existing iOS SDK versions will remain available through CocoaPods. To keep receiving iOS SDK updates, migrate the native plugin's posthog-ios dependency to SPM using the hybrid CocoaPods and SPM setup, or use full SPM integration if your app supports it. The hybrid path keeps CocoaPods for the plugin and other React Native dependencies.

This change does not affect @posthog/react-native-plugin releases on npm or Android.

The @posthog/react-native-plugin package supports CocoaPods, the hybrid CocoaPods and Swift Package Manager path, and React Native's full Swift Package Manager integration. PostHog verifies the full path with an iOS-only React Native 0.87.1 app and React Native Community CLI 20.2.0. This path requires @posthog/react-native-plugin 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target.

See iOS dependency paths for the React Native native plugin for the requirements and setup steps. This verification does not cover Expo or other React Native versions. Use CocoaPods or the hybrid path unless you validate full Swift Package Manager for your configuration.