React Native

How to Fix "Unable to Load Script. Make Sure You're Running a Bundler" in Android

4 min read by DebuggedIt

Quick answer

Your React Native app builds and installs on an Android device or emulator, but instead of loading your app, it shows a red error screen saying it can't find...

Your React Native app builds and installs on an Android device or emulator, but instead of loading your app, it shows a red error screen saying it can't find the JavaScript bundle. This means the native Android app successfully launched, but it couldn't reach Metro, the development server responsible for serving your JavaScript.

The Problem

The app installs and opens, but instead of your UI you get an error screen:

Unable to load script. Make sure you're either running Metro (run 'npx react-native
start') or that your bundle 'index.android.bundle' is packaged correctly for release.

Checking the Metro terminal often shows no connection attempt logged at all, confirming the app never actually reached it:

Metro waiting on http://localhost:8081
(no request logged when the app tries to load)
Device needs a path back to Metro Metro :8081 Android device can't reach localhost:8081 no route, unless forwarded Fix: adb reverse tcp:8081 tcp:8081 (emulator/USB)

Why It Happens

The Android app, whether on a physical device or an emulator, needs an actual network path to reach Metro, which runs on your development machine — "localhost" from the device's perspective is the device itself, not your computer, so this connection doesn't work automatically without help. This happens for a handful of specific reasons:

  • Metro isn't actually running — the simplest cause, but easy to overlook if a previous terminal session was closed.
  • Missing ADB port forwarding for a physical device connected via USB — Android needs an explicit adb reverse command to route the device's requests for localhost:8081 back to your machine's Metro instance.
  • A firewall on your development machine is blocking incoming connections on port 8081, relevant when connecting over Wi-Fi rather than USB.
  • The emulator or device is on a different network segment than your development machine, when connecting over Wi-Fi rather than through USB/ADB.
  • The app was built in release mode, which expects a bundled JavaScript file rather than a live Metro connection, but no bundle was actually packaged into the build.

The Fix

First, confirm Metro is actually running:

npx react-native start

For a physical Android device connected via USB, set up port forwarding so the device can reach Metro on your machine through the USB connection — this is the single most common fix for this exact error:

adb reverse tcp:8081 tcp:8081

Confirm the device is actually visible to ADB first if this command fails:

adb devices
List of devices attached
R58M12ABCDE	device

Reload the app after setting up the forward:

# Shake the device or press R twice on the keyboard for the emulator, or:
adb shell input keyevent 82

For an emulator, adb reverse typically isn't necessary since Android emulators can usually reach 10.0.2.2 as an alias for your host machine's localhost — but if it's still failing, explicitly set the debug server host in the app's developer menu:

# In the in-app developer menu (shake gesture or Cmd+M / Ctrl+M)
# Settings -> Debug server host & port for device -> 10.0.2.2:8081

If connecting over Wi-Fi rather than USB, find your development machine's actual local network IP and configure the device to use that instead of localhost:

ipconfig getifaddr en0   # macOS, get your machine's local IP
# In the app's developer menu, set:
# Debug server host & port for device -> 192.168.1.42:8081

Make sure your machine's firewall allows incoming connections on port 8081 for this to work over Wi-Fi.

Still Not Working?

If Metro is confirmed running and reachable but the app still can't load the script, check the Metro terminal output directly while reloading the app — a connection attempt that fails partway through (rather than never arriving at all) usually indicates a JavaScript bundling error, which is a different problem from a pure connectivity issue and shows up as actual error text in the Metro terminal rather than silence:

# Watch Metro's terminal output while reloading the app on device
npx react-native start --verbose

If you see a bundling error there instead of a connection log, the fix is in your JavaScript code or a broken import, not in networking configuration — resolve that error first, and the "unable to load script" screen should resolve itself as a downstream consequence once Metro can successfully build and serve the bundle.

You might also like