Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

A React Native app on a physical phone cannot reach the Metro server

ErrorConnection to http://localhost:8081/debugger-proxy?role=client timed out. Are you running node proxy?

Short answer

A phone cannot use localhost, so a debug build must find Metro at your computer's address. On iOS the usual causes are different networks or a Wi-Fi that blocks device-to-device traffic, and a wrong IP baked into the build. On Android, run adb reverse tcp:8081 tcp:8081 or enter the host in Dev Settings.

  • Applies to React Native CLI template, Metro, Xcode 26, Android platform-tools, physical iPhone and Android phone
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Start Metro on the computer and check the phone and the computer are on the same Wi-Fi. For Android over USB also list the device; the state must read device.

    npx react-native start
    adb devices
  2. 2Match what you see, then jump to its fix

    1. 1The app opens with the red error screen and Metro shows no request from the phoneiOS: the phone and the Mac are not on the same network, or the network blocks device-to-device trafficFix
    2. 2The error shows an address that is not your computer's current addressiOS: the build embeds an old or wrong IP addressFix
    3. 3adb devices lists the phone as unauthorized, or the app shows: bridge configuration isn't availableAndroid over USB: the device is unauthorized or there is no port forward to MetroFix
    4. 4The app is installed and opens with a red screen, with no USB cable in useAndroid over Wi-Fi: the debug server host is not setFix

What does the error look like?

  • Connection to http://localhost:8081/debugger-proxy?role=client timed out. Are you running node proxy?
  • bridge configuration isn't available

Cause 1 of 4

iOS: the phone and the Mac are not on the same network, or the network blocks device-to-device traffic

1Check

React Native needs the Mac and the iPhone on the same Wi-Fi. Its docs add that open networks with captive portals often block this kind of traffic.

# Mac: System Settings > Network shows the Mac's address; the iPhone: Settings > Wi-Fi shows its network name

2Fix

Join both devices to the same private Wi-Fi. If the network blocks traffic between devices, use the iPhone Personal Hotspot and join the Mac to it, or share the Mac connection to the device over USB.

# iPhone: Settings > Personal Hotspot on, then join the Mac to it and rebuild the app

3Verify

Reload the app: the red error screen is gone and the bundle loads.

# shake the device > Reload

Confirmed by reactnative.dev

Did this fix it?

Cause 2 of 4

iOS: the build embeds an old or wrong IP address

1Check

In Xcode open the Report navigator, select the latest Build and search the log for IP=. The React Native docs say that address should match your machine's.

# Xcode: Report navigator > latest Build > search for IP=

2Fix

If the address is old, for example after changing network or moving between home and office, rebuild the app so the build step records the current address.

# Xcode: Product > Run on the connected device

3Verify

The new build log shows your current IP and the app connects.

# Xcode: Report navigator > latest Build > search for IP=

Confirmed by reactnative.dev

Did this fix it?

Cause 3 of 4

Android over USB: the device is unauthorized or there is no port forward to Metro

1Check

The React Native docs say device means connected and unauthorized needs you to accept USB debugging on the phone. Only one device should be connected at a time.

adb devices

2Fix

Accept the USB debugging prompt on the phone, then forward the Metro port from the phone to the computer. The docs call adb reverse the recommended method for Android 5.0 and later.

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

3Verify

Reload the app from the Dev Menu; it now loads the bundle over USB.

adb devices

Confirmed by reactnative.dev

Did this fix it?

Cause 4 of 4

Android over Wi-Fi: the debug server host is not set

1Check

Over Wi-Fi the phone must be told your computer's address. Install the app over USB first, make sure both are on the same Wi-Fi, then open the in-app Dev Menu.

# macOS: System Settings > Network. Windows: ipconfig. Linux: /sbin/ifconfig

2Fix

In the Dev Menu choose Dev Settings, then Debug server host and port for device, and enter your computer's address and the Metro port, for example 10.0.1.1:8081. Return to the menu and choose Reload JS.

# Dev Menu > Dev Settings > Debug server host & port for device: <computer IP>:8081

3Verify

Reload JS loads the bundle with no red screen.

# Dev Menu > Reload JS

Confirmed by reactnative.dev

Did this fix it?

How do I stop it coming back?

  • Use the same trusted Wi-Fi for the computer and the phone, and avoid guest or captive-portal networks for development.
  • On Android prefer adb reverse over USB; it does not depend on the router.
  • Rebuild the iOS debug app after you change networks.

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

Next step

Want this handled for good?

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