A React Native app on a physical phone cannot reach the Metro server
Connection 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.
Fix it fast
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 devices2Match what you see, then jump to its fix
- 1
The 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
The error shows an address that is not your computer's current addressiOS: the build embeds an old or wrong IP addressFix - 3
adb 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
The 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
- 1
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 name2Fix
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 app3Verify
Reload the app: the red error screen is gone and the bundle loads.
# shake the device > ReloadConfirmed by reactnative.dev
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 device3Verify
The new build log shows your current IP and the app connects.
# Xcode: Report navigator > latest Build > search for IP=Confirmed by reactnative.dev
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 devices2Fix
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:80813Verify
Reload the app from the Dev Menu; it now loads the bundle over USB.
adb devicesConfirmed by reactnative.dev
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/ifconfig2Fix
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>:80813Verify
Reload JS loads the bundle with no red screen.
# Dev Menu > Reload JSConfirmed by reactnative.dev
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:
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Mobile apps
Axios request works on iOS or in a browser but fails on Android with Network Error
AxiosError: Network Error
A React Native app has no CORS, so on Android a Network Error usually means the request never reached the server.
3 causes, each with a fixMobile apps
Axios returns Network Error in a React Native app on iPhone or the iOS Simulator
error.code is ERR_NETWORK and error.response is undefined
A Network Error means iOS stopped the request before any HTTP answer came back.
3 causes, each with a fixMobile apps
backgroundImage: url(...) does nothing in a React Native view
ImageBackground renders an empty area
In React Native the backgroundImage style draws linear and radial gradients, not pictures, so url(...) is ignored.
3 causes, each with a fixMobile apps
A custom font in React Native falls back to the system font
Unrecognized font family 'MyFont'
React Native does not report a missing font, it just draws the system font.
6 causes, each with a fixMobile apps
fetch fails with TypeError: Network request failed in React Native
Network request failed
Network request failed means the request never got an HTTP response, so there is no status code to read.
3 causes, each with a fixMobile apps
react-native-geolocation-service getCurrentPosition fails or never returns
Location provider not available
Read the error code in the callback.
5 causes, each with a fix