Diagnosing React Native Crashes and Freezes After Enabling Hermes

Recognizable Symptoms

After toggling hermes:true in react-native.config.js or the package.json flag, users often see:

• App launches but immediately crashes with a stack trace referencing HermesRuntime or ModuleNotFoundException.
• UI freezes or stutters when rendering large lists or heavy images.
• Native modules throw runtime errors like Cannot find module 'react-native-some-module'.
• Build fails with errors about missing hermes-engine dependency.
• Console logs show repeated Garbage collection warnings.

Root Causes Table

Cause	Typical Symptom	Quick Check
Hermes flag not enabled in config	App crashes on start	Verify react-native.config.js or package.json
Native module compiled for JSC only	Runtime exception in native code	Run react-native info | grep Hermes
Missing hermes-engine in Gradle or Podfile	Build error: cannot find hermes module	Check Android Gradle build.gradle and iOS Podfile
RN version < 0.64	Build fails when enabling Hermes flag	Run react-native --version
Legacy code using JSC‑only APIs (e.g., eval patterns)	Crashes or no‑op in JS runtime	Search codebase for JSC‑only features
Memory leaks or excessive GC pauses in Hermes	UI freezes on large data sets	Profile memory usage with Android Studio or Xcode

Systematic Checks

1. Confirm Hermes is enabled

   # In project root
   $ react-native info | grep Hermes
   Hermes: true
   

2. Validate RN version

   $ react-native --version
   0.68.2
   

   If version < 0.64, upgrade before enabling Hermes.
3. Inspect build scripts
   • Android: android/app/build.gradle should contain

     project.ext.react = [
         hermesEnabled: true
     ]
     

   • iOS: ios/Podfile must include

     use_react_native!(:hermes_enabled => true)
     

4. Check native module compatibility

   # List installed pods or Gradle dependencies
   $ pod list | grep hermes
   $ ./gradlew dependencies | grep hermes
   

   If a module shows react-native-xyz (JSC only), consider updating or replacing it.
5. Examine startup logs
   • Android: adb logcat | grep Hermes
   • iOS: Xcode console or log -s Hermes
6. Profile memory for GC spikes

   # Android Studio Profiler → Memory → GC events
   # Xcode Instruments → Allocations → Heap

Targeted Fixes

• Enable the flag correctly

  // react-native.config.js
  module.exports = {
    project: {
      ios: {},
      android: {},
    },
    dependencies: {},
    hermes: true,
  };
  

• Upgrade native modules

  # Example: react-native-gesture-handler
  $ npm install react-native-gesture-handler@latest
  $ cd ios && pod install
  

• Add Hermes dependency to Gradle

  // android/app/build.gradle
  dependencies {
      implementation "org.webkit:android-jsc-intl:1.10.0"
      implementation "org.webkit:android-jsc:1.10.0"
      implementation "org.webkit:hermes-engine:0.9.0"
  }
  

• Remove JSC‑only code
  • Replace eval('...') with Function('...')() or static parsing.
  • Eliminate global.__fbBatchedBridge usage.
• Optimize data handling
  • Use FlatList with removeClippedSubviews and initialNumToRender tuned.
  • Chunk large JSON payloads before passing to JS.
• Clear caches

  # Android
  $ cd android && ./gradlew clean
  # iOS
  $ cd ios && pod deintegrate && pod install
  # RN
  $ npm cache clean --force
  $ watchman watch-del-all
  $ rm -rf node_modules && npm install
  

Escalation Criteria

1. If the app still crashes after confirming all configuration steps, open an issue on the module’s GitHub repo with logs.
2. For persistent UI freezes on iOS, file a bug with Xcode Instruments data.
3. If memory profiling shows constant GC spikes with no obvious cause, consider disabling Hermes temporarily to isolate the problem.
4. When build fails due to Gradle or CocoaPods errors, consult the official Hermes documentation for the latest dependency versions.

Quick Reference

• Hermes flag: hermes:true in react-native.config.js
• Android Gradle: project.ext.react = [hermesEnabled:true]
• iOS Podfile: use_react_native!(:hermes_enabled => true)
• Check Hermes status: react-native info | grep Hermes
• Android log: adb logcat | grep Hermes
• iOS log: log -s Hermes