Debugging Android Connectivity Issues with Metro Bundler

Whether you just start with or are seasoned React Native developer, chances are you faced the "Unable to load script" error occurring on Android emulator when your app can't connect to the Metro Bundler.

In this article we’ll explore steps you can take to debug and resolve this dreaded error.

Check Metro Bundler

When you open your app in debug mode and there’s no dev server running (Metro in this case), it’s pretty reasonable to get an error that your app is unable to load script. Ensure that the Metro Bundler by running:

npx react-native start

When the server is running, you should be able to access http://localhost:8081 link from any web browser.

Reverse Port for Emulator

For android emulator to be able to connect to our local dev server, we need to reverse the port on which it listens. Normally it’s taken care of by RNC CLI, RNEF, or Expo, but sometimes it may not kick in properly. In such cases run this command to make sure the emulator can connect to your local dev server hosted on http://localhost:8081:

adb reverse tcp:8081 tcp:8081

If you use different port, please change 8081 to your designated port.

Network Configuration

By default Android apps that target API level 28 or higher will use encrypted protocols to connect with outside world. In our case, we want our app to connect to unencrypted HTTP address localized at http://localhost:8081.

Confirm that your android:usesCleartextTraffic in debug AndroidManifest.xml file is enabled in debug mode. Check or create android/app/src/debug/AndroidManifest.xml to look somewhat like this:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">

    <application
        android:usesCleartextTraffic="true"
        tools:targetApi="28"
        tools:ignore="GoogleAppIndexingWarning"/>
</manifest>

Network Security Config

If your app is configured to use Network Security (located at res/xml/network_security_config.xml), make sure that localhost and 10.0.2.2 (gateway from Android Emulator to your dev machine) are included in your network security configuration:

<domain-config cleartextTrafficPermitted="true">
    <domain includeSubdomains="true">10.0.2.2</domain>
    <domain includeSubdomains="true">localhost</domain>
</domain-config>

Clear Emulator Data

If the issue persists, try wiping data and performing a cold boot on your emulator.

Proxy/Firewall

Make sure no proxies or firewalls are blocking port 8081.

Final Step

If your app builds fine on iOS but not Android, inspect third-party tools and configurations that may affect network settings, such as Proxyman. Remove conflicting configurations and test again. By following these steps, you should be able to troubleshoot and resolve Android connectivity issues effectively. Remember to only enable cleartext traffic in debug variants to maintain app security.