Quick Troubleshooting Flow

Use this flow when React Native wireless debugging stops working.

flowchart TD A[START] --> B["adb devices -l"] B --> C{"No device or device?"} C -->|"No device"| D["Check ADB/USB/Wi-Fi"] D --> E["adb connect IP:5555"] E --> F{"device found?"} F -->|Yes| G["Run React Native run-android"] F -->|No| D C -->|device| G G --> H{"Build error or success?"} H -->|"Build error"| I["SDK/Gradle/Java"] H -->|"Build successful"| J["APK installation"] J --> K{"Installation result?"} K -->|"Fails"| L["Read exact error"] K -->|"Succeeds"| M{"App launches?"} L --> N{"Error type?"} N -->|EOF| O["ADB problem"] N -->|"No space"| P["Free phone storage"] N -->|offline| Q["Fix ADB connection"] M -->|"Works"| R["Metro OK"] M -->|"Doesn't work"| S["Metro problem"] S --> T{"Metro running?"} T -->|NO| U["npx react-native start"] T -->|YES| V["Check port 8081"] V --> W{"adb reverse or Direct Wi-Fi?"} W -->|"adb reverse tcp:8081"| X{"Works?"} X -->|YES| R X -->|NO| Y["Check React Native config"] W -->|"Direct Wi-Fi PC_IP:8081"| Z{"Browser test"} Z -->|Works| AA["Network OK"] Z -->|Fails| AB["Firewall/router/network isolation"]

1. Check the Device

cmd 
adb devices -l

Expected:

text 
192.168.1.15:5555    device

If offline

cmd 
adb kill-server
adb start-server
adb devices

If necessary, reconnect the phone:

cmd 
adb connect PHONE_IP:5555

If no device appears

Check:

  • Phone is connected to the same Wi-Fi.
  • USB debugging is enabled when using USB.
  • Phone's IP address is correct.
  • ADB TCP mode is enabled.
cmd 
adb tcpip 5555
adb connect PHONE_IP:5555

2. Run React Native

bash 
npx react-native run-android

Now identify where the command fails.

3. Build Fails

If Gradle fails before installing the APK, investigate:

  • Android SDK
  • android/local.properties
  • Java/JDK
  • Gradle
  • Build Tools
  • Project dependencies

For example:

text 
SDK location not found

-> Check Android SDK configuration.

Then:

cmd 
cd android
gradlew clean
cd ..

Try again:

bash 
npx react-native run-android

4. Build Successful → Installation Fails

If you see BUILD SUCCESSFUL but :app:installDebug FAILED, the build itself succeeded. Read the actual installation error.

Requested internal only, but not enough space

-> Free storage on the device.

cmd 
adb shell df -h /data

InstallException: EOF

-> Investigate ADB/device communication.

Try:

cmd 
adb devices

Then manually install the APK:

cmd 
adb install -r "C:\\android\app\build\outputs\apk\debug\app-debug.apk"

If manual installation succeeds, the APK is valid.

5. APK Installs Successfully

If Performing Streamed Install / Success, then APK installation is working.

Launch the app if necessary:

cmd 
adb -s PHONE_IP:5555 shell am start -n com.yourapp/.MainActivity

If the app launches but shows Unable to load script, move to Metro troubleshooting.

6. Metro Troubleshooting

Start Metro:

bash 
npx react-native start

You should see:

text 
Welcome to Metro
INFO  Dev server ready.

If Metro says No apps connected, check:

cmd 
adb devices

7. Try ADB Reverse

For the connected device:

cmd 
adb -s PHONE_IP:5555 reverse tcp:8081 tcp:8081

Check:

cmd 
adb -s PHONE_IP:5555 reverse --list

Expected:

text 
tcp:8081 tcp:8081

Then reload/restart the app.

8. If adb reverse Doesn't Work

Try accessing Metro directly from the phone.

Find the PC's IP:

cmd 
ipconfig

Example:

text 
PC     = 192.168.1.14
Phone  = 192.168.1.15

Remember:

text 
Phone IP -> ADB
PC IP    -> Metro

Open on the phone:

text 
http://192.168.1.14:8081

9. Phone Browser Can't Open PC_IP:8081

Check in this order:

text 
Metro running?
      |
Correct PC IP?
      |
Port 8081 listening?
      |
Windows Firewall?
      |
Same Wi-Fi?
      |
Router/client isolation?

Check port:

cmd 
netstat -ano | findstr :8081

If nothing is listening, Metro is probably not running on port 8081.

10. Phone Browser Can Open Metro

If http://PC_IP:8081 opens successfully:

text 
Phone -> PC network connection works
Port 8081 is reachable
Metro is running

If React Native still shows Unable to load script, investigate the React Native development-server configuration rather than the router.

The 5-Step Rule

When something fails, identify the stage first:

text 
1. ADB
   |
2. Gradle Build
   |
3. APK Installation
   |
4. App Launch
   |
5. Metro / Port 8081

Don't troubleshoot all five at once.

Quick Command Checklist

cmd 
:: 1. Check device
adb devices -l

:: 2. Check ADB version
adb version

:: 3. Connect wireless device
adb connect PHONE_IP:5555

:: 4. Check PC IP
ipconfig

:: 5. Check port 8081
netstat -ano | findstr :8081

:: 6. Reverse Metro
adb -s PHONE_IP:5555 reverse tcp:8081 tcp:8081

:: 7. Check reverse
adb -s PHONE_IP:5555 reverse --list

:: 8. Manually install APK
adb install -r "PATH_TO_APP_DEBUG_APK.apk"

Then:

bash 
# Start Metro
npx react-native start

# Run React Native
npx react-native run-android

Most Important Rule

Always find the last stage that succeeded before troubleshooting.

For example:

text 
BUILD SUCCESSFUL
       |
APK installation FAILED

-> Don't troubleshoot Metro yet.

Or:

text 
BUILD SUCCESSFUL
       |
APK installation SUCCESSFUL
       |
App launches
       |
Unable to load script

-> Don't troubleshoot Gradle or APK installation anymore. Focus on Metro and port 8081.