Question 1

How do I fix CocoaPods installation errors for iOS?

Accepted Answer

Error:

[!] CocoaPods could not find compatible versions for pod "GlobalExceptionHandler"

Solution:

1. Update CocoaPods:
sudo gem install cocoapods

2. Clean and reinstall:
cd ios
rm -rf Pods Podfile.lock
pod deintegrate
pod install
cd ..

See the Troubleshooting doc for exact commands and additional context.

Question 2

What should I do when Android build fails with dependency errors?

Accepted Answer

Error example:

Could not determine the dependencies of task ':app:compileDebugJavaWithJavac'

Solution:

1. Ensure your android/build.gradle has the correct Kotlin version, e.g.:
buildscript {
  ext {
    kotlinVersion = "1.8.0"
  }
}

2. Clean gradle cache and rebuild:
cd android
./gradlew clean
./gradlew cleanBuildCache
cd ..

Then re-run your build. See the Troubleshooting doc for full steps.

Question 3

How can I simulate a native crash for testing?

Accepted Answer

Steps:

1. Ensure you're on a supported platform (iOS or Android) and running on a real device or supported simulator.
2. Call the provided simulation API (example):
import { simulateNativeCrash } from 'react-native-global-exception-handler';

simulateNativeCrash('nsexception');

3. Guard simulation code from production using __DEV__:
if (__DEV__) {
  global.simulateCrash = () => simulateNativeCrash('nsexception');
}

Verify the crash type is valid for your platform. If the simulation has no effect, confirm you are not running in an unsupported environment (e.g., web).

Question 4

simulateNativeCrash has no effect — how do I fix it?

Accepted Answer

If simulation doesn't work:

1. Ensure you're on iOS/Android (not web).
2. Verify Platform.OS and only call simulation on supported platforms. Example:
import { Platform } from 'react-native';

if (Platform.OS === 'ios' || Platform.OS === 'android') {
  simulateNativeCrash('nsexception');
} else {
  console.log('Not supported on this platform');
}

3. Confirm the crash type is valid for the platform.

Question 5

How can I enable JS exception handler in development?

Accepted Answer

To enable the JS exception handler in development pass true as the second parameter:
setJSExceptionHandler((error, isFatal) => {
  // Your handler
}, true); // ← enable in dev mode

Note: Native handlers may still be affected by debug tooling; test native handlers in release builds when possible.

Question 6

Why does the native handler not trigger in development?

Accepted Answer

In debug mode React Native's debug infrastructure can interfere with native exception handling. Test native handlers in release builds where debug tooling won't intercept uncaught exceptions.

Question 7

Why doesn't the app restart after a crash and how can I provide restart functionality?

Accepted Answer

On Android, ensure you pass forceAppToQuit for proper cleanup:
setNativeExceptionHandler((errorString) => {
  // Handle error
}, {
  forceAppToQuit: true // Required for proper cleanup
});

On iOS there is no programmatic restart — show a custom error screen and instruct the user to restart the app.

Question 8

When should I set `forceAppToQuit` to false?

Accepted Answer

Use cases for forceAppToQuit: false:

- When using navigation libraries (e.g., react-native-navigation) that recreate the app stack and can handle recovery.
- When you have custom native recovery logic and want the app to attempt recovery instead of forcing a quit.

Example:
setNativeExceptionHandler((errorString) => {
  console.log('Native error:', errorString);
  reportToAnalytics(errorString);
}, {
  forceAppToQuit: false,
  callPreviouslyDefinedHandler: true
});

Note: In many cases forceAppToQuit: true is safer for clean crash handling.

Question 9

Errors are captured but not sent to my analytics service — what now?

Accepted Answer

Common fixes:

1. Check network connectivity from within your handler.
2. Queue errors locally for retry using AsyncStorage. Example:
import AsyncStorage from '@react-native-async-storage/async-storage';

const queueError = async (error) => {
  const queue = await AsyncStorage.getItem('error_queue');
  const errors = queue ? JSON.parse(queue) : [];
  errors.push(error);
  await AsyncStorage.setItem('error_queue', JSON.stringify(errors));
};

setJSExceptionHandler((error, isFatal) => {
  queueError({ error, isFatal });
}, true);

This ensures errors persist until they can be sent.

Question 10

Why does app performance degrade after setting exception handlers?

Accepted Answer

Keep handlers lightweight. Avoid heavy synchronous work that blocks the event loop.

Bad example (heavy synchronous work):
// ❌ Bad
setJSExceptionHandler((error, isFatal) => {
  const largeData = processHugeDataset();
  sendToServer(largeData);
}, true);

Good example (deferred async work):
// ✅ Good
setJSExceptionHandler((error, isFatal) => {
  setTimeout(() => {
    sendToServer(error);
  }, 0);
}, true);

Question 11

How do I prevent memory leaks caused by error handlers?

Accepted Answer

Avoid capturing large variables in closures that handlers use.

Bad example (captures largeData):
let largeData = /* ... */;
setJSExceptionHandler((error, isFatal) => {
  console.log(largeData); // Keeps largeData in memory
}, true);

Better approach: fetch fresh data when needed inside the handler so large references are not retained.

Question 12

Why am I seeing 'TurboModuleRegistry.getEnforcing' errors?

Accepted Answer

This error is usually specific to the React Native new architecture (TurboModules).

Example:
TurboModuleRegistry.getEnforcing called for module 'GlobalExceptionHandler' but it is not registered

Solution:

1. Ensure you're using React Native 0.68 or higher.
2. Clear Metro cache and restart:
npx react-native start --reset-cache
3. Clean and rebuild (iOS/Android):
# iOS
cd ios && rm -rf Pods && pod install && cd ..
npx react-native run-ios

# Android
cd android && ./gradlew clean && cd ..
npx react-native run-android

Question 13

How can I fix TypeScript type errors when assigning handler functions?

Accepted Answer

Example:
import {
  setJSExceptionHandler,
  type JSExceptionHandler
} from 'react-native-global-exception-handler';

const handler: JSExceptionHandler = (error, isFatal) => {
  console.log(error);
};

setJSExceptionHandler(handler, true);

For native options types:
import {
  setNativeExceptionHandler,
  type ExceptionHandlerOptions
} from 'react-native-global-exception-handler';

const options: ExceptionHandlerOptions = {
  forceAppToQuit: true,
  callPreviouslyDefinedHandler: false
};

Question 14

What if my React Native version is incompatible with this library?

Accepted Answer

This library requires React Native 0.68+. If you're on an older RN version you can:

1. Upgrade React Native:
npx react-native upgrade

2. Or use an older compatible library:
npm install react-native-exception-handler

Question 15

Some features require Hermes — how do I enable it?

Accepted Answer

Enable Hermes in your app configuration.

iOS (Podfile):
use_react_native!(
  :path => config[:reactNativePath],
  :hermes_enabled => true
)

Android (android/app/build.gradle):
project.ext.react = [
    enableHermes: true
]

After enabling, reinstall pods and rebuild.

Question 16

How do I get more help if the troubleshooting steps do not fix my issue?

Accepted Answer

Steps to get help:

1. Check existing issues on GitHub: https://github.com/darshan09200/react-native-global-exception-handler/issues
2. Create a new issue including:
   - React Native version
   - Platform (iOS/Android)
   - Error message
   - Minimal reproduction code
3. Enable verbose logging for troubleshooting:
setJSExceptionHandler((error, isFatal) => {
  console.log('Error details:', {
    name: error.name,
    message: error.message,
    stack: error.stack,
    isFatal
  });
}, true);

Troubleshooting

Before you open an issue

Debug vs Release

Common issues

Installation issues

CocoaPods could not find the pod

Android build dependency failure

TurboModule is not registered

Runtime issues

JavaScript handler does not run in development

Native handler seems broken in debug mode

App does not restart after a crash

Another SDK handler stopped running

When should `forceAppToQuit` be false?

Testing issues

`simulateNativeCrash` does nothing

Test crash code leaked into production

Analytics issues

Errors are not reaching Sentry or Crashlytics

Next actions

Before you open an issue​

Debug vs Release​

Common issues​

Installation issues​

CocoaPods could not find the pod​

Android build dependency failure​

TurboModule is not registered​

Runtime issues​

JavaScript handler does not run in development​

Native handler seems broken in debug mode​

App does not restart after a crash​

Another SDK handler stopped running​

When should forceAppToQuit be false?​

Testing issues​

simulateNativeCrash does nothing​

Test crash code leaked into production​

Analytics issues​

Errors are not reaching Sentry or Crashlytics​

Next actions​

Before you open an issue

Debug vs Release

Common issues

Installation issues

CocoaPods could not find the pod

Android build dependency failure

TurboModule is not registered

Runtime issues

JavaScript handler does not run in development

Native handler seems broken in debug mode

App does not restart after a crash

Another SDK handler stopped running

When should `forceAppToQuit` be false?

Testing issues

`simulateNativeCrash` does nothing

Test crash code leaked into production

Analytics issues

Errors are not reaching Sentry or Crashlytics

Next actions