React Native Hermes White Screen Release Build Fix

Diagnostic guide for React Native apps with Hermes enabled that show a blank white screen on cold start in release builds while debug builds work. Covers bundle packaging, bytecode generation and native build config.

Release builds show splash then white, debug works

With Hermes enabled, a React Native app can launch to the splash screen and then stay white or black on a cold start in release, with no red error overlay and no UI rendering. Debug builds served by Metro work fine. The useful takeaway is that this is almost always a bundle packaging or Hermes bytecode loading problem, not a JavaScript runtime error after start.

Recognizable condition

The app is installed from a release artifact built via CLI, Xcode or Gradle. On first launch after a clean install it shows the splash screen, then a blank screen. The app may eventually return to home or terminate with out-of-memory behavior. Debug builds with Metro and the same code start correctly. The failure is reproducible on a clean install and is consistent across devices for the same build.

Cause diagnostic table

Observed symptom	Likely cause
White screen immediately after splash, no logs in JS	Bundle not packaged into app assets or entry file name mismatch between Metro config and native initialization
White screen, device logs mention Hermes load failure	Hermes bytecode not generated for release or dev bundle served to release
White screen on Android release only, works in debug	ProGuard/R8 stripping Hermes classes/methods needed for bytecode loading
White screen on both platforms with New Architecture enabled	Native init aborts before JS runs due to mismatched native module autolinking or Fabric/TurboModules config

Ordered checks

Confirm Hermes is enabled and release settings are used. Check app config for Hermes enablement and verify the release build uses hermes-enabled Gradle and Xcode settings. Run from project root. Risk: changing build settings affects all variants.
```
cd android && ./gradlew clean assembleRelease
```
Expected check: build completes without skipping Hermes tasks.
Clean Metro and native caches then rebuild. Stale caches can cause an empty or missing bundle to be copied.
```
npx react-native start --reset-cache
```
Run in terminal at project root. No special permissions required. Risk: cache reset increases next build time.
Verify bundle packaging. For Android, confirm the bundle is present in android/app/src/main/assets and the file name matches the name expected by native code. For iOS, confirm the bundle is in the main app bundle. Check the entry file defined in Metro config matches the native initialization.
Inspect native startup logs on device. Use device log streaming immediately after splash to look for Hermes load messages, asset lookup failures, or class-not-found messages during startup. This confirms whether the failure point is bundle loading.

Fixes tied to findings

Missing or mismatched bundle asset

If logs show asset lookup failure, rebuild with a clean Metro cache and ensure the correct bundle is copied into android/app/src/main/assets and the iOS main bundle. Align the bundle entry file and asset name across Metro config and native initialization code. After change, perform a clean install.

Hermes bytecode generation issue

If logs indicate Hermes load errors, regenerate bytecode via the standard release build flow and avoid serving a dev bundle to release. Do not disable Hermes or ship a dev bundle as a workaround; this masks the problem and introduces performance and security risks.

ProGuard/R8 stripping on Android

If the issue is Android release only, add recommended keep rules for Hermes classes and re-enable minification. Rules differ between debug and release, so a change that works in debug may be stripped in release.

New Architecture init abort

If New Architecture is enabled and native init aborts before JS runs, verify native module autolinking and Fabric/TurboModules configuration match the React Native version in use. Align native code expectations with the JS entry point.

Escalation criteria

White screen persists after clean rebuild on both platforms with Hermes disabled working, indicating native initialization or third-party native module incompatibility.
Crash logs show native memory corruption or signals in libhermes.so.
Issue reproduces only on specific OS versions or device models suggesting OEM-specific behavior.

Limitations and verification

Behavior is version-sensitive. Hermes bytecode generation and asset packaging changed across React Native major versions and between the old architecture and the New Architecture with Fabric/TurboModules.

Verify by reproducing on a clean device install with a release build from CLI or Xcode/Gradle, not from debug Metro, and confirm white screen occurs on first launch. Check device logs for Hermes-specific load messages and asset lookup failures immediately after splash. Temporarily build a release variant with Hermes disabled; if the app starts correctly, the issue is isolated to Hermes bytecode/bundle packaging. After applying a fix, perform a clean install and cold start test on both iOS and Android physical devices to verify UI renders and no regression appears.

React Native Hermes Release White Screen on Cold Start: Diagnostic Guide