Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

React Native Android red screen: Unable to load script

ErrorUnable to load script

Short 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.

  • Applies to React Native 0.7x, Gradle 8, Android 14, Metro
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.properties
  2. 2Match what you see, then jump to its fix

    1. 1Debug build, and the red screen appears right at launch.Metro is not running, or the device cannot reach it over USBFix
    2. 2No USB cable, and the phone and laptop are on the same network.Wi-Fi device without a debug server hostFix
    3. 3The red screen shows in an installed release build, with Metro stopped.Release build without an embedded bundleFix

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 devices

2Fix

Start Metro in one terminal, then forward the port and reload.

npm start
adb -s <device name> reverse tcp:8081 tcp:8081

3Verify

Reload the app from the Dev Menu, or rerun the app.

npm run android

Confirmed by reactnative.dev

Did this fix it?

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 devices

2Fix

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:8081

3Verify

The app loads and the Metro terminal prints a bundling line.

npm start

Confirmed by reactnative.dev

Did this fix it?

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.properties

2Fix

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=release

Confirmed by reactnative.dev

Did this fix it?

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:

Related fixes

Web 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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.