White screen in release

Error text

App opens to a blank white or black screen; logcat: Unable to load script. Make sure you're either running Metro or that your bundle 'index.android.bundle' is packaged correctly for release.

Cause

The app opens but the screen stays blank. The JS bundle did not get packaged, or a JS error happened on the first render.

Step-by-step fix

1. Search adb logcat for Unable to load script or a JS error.
2. Check that the bundle file exists at assets/index.android.bundle.
3. Create the bundle by hand and run ./gradlew clean assembleRelease.
4. If a JS error blanks the screen, wrap the first screen with try/catch and an ErrorBoundary.
5. If your API address is http, read the network security config page.

Example commands

adb logcat *:E | grep -i -E "react|bundle|script"
npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res
cd android && ./gradlew clean assembleRelease

How to prevent it

Before every release install the APK on a phone without any debug tooling and open it.

Author and license: Nibras Code