React Native Android red screen: Unable to load script
Unable to load scriptShort answer
The app could not fetch its JavaScript. In a debug build the phone cannot reach Metro on port 8081: start Metro, run adb reverse tcp:8081 tcp:8081, or set the debug host. In a release build the bundle was not packaged, and a Gradle setting can cause that.
Fix it fast
1Find out which cause you have
Decide whether this is a debug or a release build. Debug builds fetch JavaScript from Metro; release builds carry it inside the app.
adb devices grep -n configureondemand android/gradle.properties2Match what you see, then jump to its fix
- 1
Debug build, and the red screen appears right at launch.Metro is not running, or the device cannot reach it over USBFix - 2
No USB cable, and the phone and laptop are on the same network.Wi-Fi device without a debug server hostFix - 3
The red screen shows in an installed release build, with Metro stopped.Release build without an embedded bundleFix
- 1
What does the error look like?
Unable to load script
Cause 1 of 3
Metro is not running, or the device cannot reach it over USB
1Check
The app loads JavaScript from the development server on your machine, port 8081 by default. A USB device needs a port forward to reach it, and only one device should be connected.
adb devices2Fix
Start Metro in one terminal, then forward the port and reload.
npm start
adb -s <device name> reverse tcp:8081 tcp:80813Verify
Reload the app from the Dev Menu, or rerun the app.
npm run androidConfirmed by reactnative.dev
Cause 2 of 3
Wi-Fi device without a debug server host
1Check
Over Wi-Fi the app needs your machine's IP address and port. Both devices must be on the same network.
adb devices2Fix
In the in-app Dev Menu open Dev Settings, then Debug server host and port for device. Enter your machine's address, such as 10.0.1.1:8081, and choose Reload JS.
# Dev Menu > Dev Settings > Debug server host & port for device > 10.0.1.1:80813Verify
The app loads and the Metro terminal prints a bundling line.
npm startConfirmed by reactnative.dev
Cause 3 of 3
Release build without an embedded bundle
1Check
A release build packs all JavaScript into the app, so it needs no Metro. The release guide warns that org.gradle.configureondemand=true makes the release build skip bundling JavaScript and assets.
grep -n "configureondemand" android/gradle.properties2Fix
Remove that line from android/gradle.properties, uninstall the old app from the device, and build the release again.
npm run android -- --mode="release"3Verify
Stop Metro and open the release app. It should start without the red screen.
npm run android -- --mode=releaseConfirmed by reactnative.dev
How do I stop it coming back?
- Keep adb reverse in your run script so a reconnected USB device keeps working.
- Test every release build with Metro stopped before you upload it.
- Keep org.gradle.configureondemand out of gradle.properties on projects that ship release builds.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
Axios get works with a URL string but ignores the object passed as the second argument
The server log shows a GET with no query string
axios.get takes a URL and an optional config object.
3 causes, each with a fixWeb apps
Expo app never leaves the splash screen
App shows the splash screen forever and no error appears
After SplashScreen.preventAutoHideAsync() the splash stays until you hide it yourself.
3 causes, each with a fixWeb apps
NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView
Error: NativeViewGestureHandler must be used as a descendant of GestureHandlerRootView. Otherwise the gestures will not be recognized.
react-native-gesture-handler only recognises gestures inside GestureHandlerRootView.
3 causes, each with a fixWeb apps
React Hook "useState" cannot be called at the top level, or in a function that is not a component
The lint points at a useState line inside a helper function, an onClick handler or the top of a module
The lint rule found a hook outside a component or custom hook.
3 causes, each with a fixWeb apps
React: Maximum update depth exceeded or Too many re-renders
Maximum update depth exceeded
React stops a component that sets state again and again without end.
3 causes, each with a fixWeb apps
React Native says the application has not been registered
Application has not been registered
The native side asks JavaScript to run an app name that JavaScript never registered.
3 causes, each with a fix