Android failed to load JS bundle

Encountering the dreaded “Android failed to load JS bundle” error can be a significant roadblock for any developer working with React Native. This message typically appears when your Android application, whether running on an emulator or a physical device, cannot connect to the Metro Bundler, the JavaScript bundler for React Native. This means the app can’t fetch the necessary JavaScript code to run. It’s a common hurdle, often stemming from network configuration issues, incorrect IP addresses, or the bundler simply not running. Understanding the root causes and systematic troubleshooting steps is crucial for efficiently resolving this error and getting your development workflow back on track. This guide will walk you through the common culprits and provide actionable solutions to overcome this frustrating problem.

Understanding the “Android Failed to Load JS Bundle” Error

At its core, the “Android failed to load JS bundle” error signifies a communication breakdown. In a typical React Native development setup, your Android app, when launched in debug mode, doesn’t contain the full JavaScript code within its APK. Instead, it relies on fetching this code, known as the JavaScript bundle, from the Metro Bundler running on your development machine. The Metro Bundler processes your React Native code, compiles it, and serves it over a local development server.

This dynamic loading allows for fast iteration during development, as you don’t need to recompile the entire Android application every time you make a JavaScript code change. When the error occurs, it means the Android app’s attempt to connect to this server and download the bundle has failed. This could be due to the server not being active, the device not being able to reach the server’s IP address and port, or various network-related impediments. This particular JS bundle error is a strong indicator that your development environment’s connectivity needs attention, especially concerning how your Android device or emulator communicates with your host machine.

The seamless interaction between your Android debug build and the Metro Bundler is vital for efficient React Native development. Without a successful connection, the application simply cannot render its UI or execute any JavaScript logic, leaving you with a blank screen or an error message. Addressing this problem effectively requires a methodical approach to diagnose where the connection is failing, whether it’s on the device side, the host machine side, or somewhere in between the network configuration.

Common Causes and Initial Diagnostics

The “Android failed to load JS bundle” error is frequently a symptom of underlying network or configuration issues. Pinpointing the exact cause often involves checking a few key areas. One of the most prevalent reasons is that the Metro Bundler isn’t running or accessible. Your React Native project needs an active bundler instance, typically started with npm start or yarn start in your project directory. If it’s not running, or if it crashed, your app won’t have a source for the JavaScript bundle.

Another common culprit is incorrect IP address or port configuration. By default, Android emulators often map 10.0.2.2 to your host machine’s localhost, but physical devices require a direct IP address. If your device is trying to connect to the wrong IP, or if the port (defaulting to 8081 for Metro) is blocked or incorrect, the connection will fail. Firewalls on your development machine can also silently block incoming connections to the Metro Bundler, preventing your device from reaching it. This is a crucial area to investigate when you encounter the JS bundle error.

Furthermore, cache corruption can sometimes lead to obscure errors. React Native development relies on various caches (Metro’s cache, Watchman cache, npm/yarn cache) to speed up builds. If these caches become corrupted, they might serve stale or malformed data, leading to bundling failures even if the network connection appears fine. Performing a clean sweep of these caches is often a recommended initial troubleshooting step. Addressing these common issues systematically can quickly resolve most instances of the “Android failed to load JS bundle” problem.

Step-by-Step Troubleshooting Guide

When you encounter the “Android failed to load JS bundle” error, a systematic approach to debugging Android apps is key. Follow these steps to diagnose and resolve the issue efficiently:

1. Verify Metro Bundler Status:

   Ensure your Metro Bundler is running. Navigate to your project directory in your terminal and run npm start or yarn start. Confirm that it’s actively bundling and listening on port 8081 (or your configured port). If it stops, restart it. If you see errors in the bundler’s output, address those first.

2. Check Network Connectivity (ADB Reverse):

   For physical Android devices, you need to ensure the device can access your computer’s Metro Bundler. Use adb reverse tcp:8081 tcp:8081. This command forwards traffic from the device’s port 8081 to your computer’s port 8081, bypassing most network configuration issues. For emulators, this is usually handled automatically, but if you’re having issues, you can try manually setting the debug server host and port in the developer options by shaking the device/emulator to open the dev menu.

3. Clear Caches and Rebuild:

   Stale caches can often cause persistent issues. In your project directory, try these commands:

   • npm start -- --reset-cache (or yarn start --reset-cache) to reset Metro’s cache.
   • watchman watch-del-all to clear Watchman’s cache.
   • rm -rf node_modules && npm install (or yarn install) to reinstall dependencies if necessary.
   • Finally, uninstall the app from your device/emulator and then rebuild and reinstall it: cd android && ./gradlew clean && cd .. && react-native run-android.

4. Verify IP Address in Developer Settings:

   If adb reverse isn’t working or for older React Native versions, you might need to manually set the debug server host. Shake your device/emulator to open the React Native developer menu. Go to “Dev Settings” -> “Debug server host & port for device”. Enter your computer’s IP address (e.g., 192.168.1.XX:8081). You can find your computer’s IP address using ipconfig (Windows) or ifconfig (macOS/Linux).

5. Check Firewall and Antivirus:

   Your computer’s firewall or antivirus software might be blocking the connection to port 8081. Temporarily disable them to see if the issue resolves. If it does, Question & Answer :

   I’m trying to run AwesomeProject on my Nexus5 (android 5.1.1).

   I’m able to build the project and install it on the device. But when I run it, I got a red screen saying

   Unable to download JS bundle. Did you forget to start the development server or connect your device?

   In react native iOS, I can choose to load jsbundle offline. How can I do the same thing for Android? (Or at least, where can I configure the server address?)

   Update

   To run with local server, run the following commands under your react-native project root directory

   1. react-native start > /dev/null 2>&1 &
   2. adb reverse tcp:8081 tcp:8081

   please take a look at dsissitka’s answer for more details.

   To run without a server, bundle the jsfile into the apk by running:

   1. create an assets folder under android/app/src/main
   2. curl "http://localhost:8081/index.android.bundle?platform=android" -o "android/app/src/main/assets/index.android.bundle"

   please take a look at kzzzf’s answer for more details.

   To bundle JS file into your apk while having your server running (react-native start) download bundle into assets directory of your app:

   curl "http://localhost:8081/index.android.bundle?platform=android" -o "android/app/src/main/assets/index.android.bundle" 
   

   With the next release (0.12) we’ll fix react-native bundle command to work with android projects as expected.