TypeError: Network request failed, explained and fixed

In React Native, a fetch that cannot complete at the network level throws TypeError: Network request failed. It deliberately carries no detail, and it is different from an HTTP error: a 404 or 500 response is a completed request and does not throw this. This error means no response arrived at all. The causes are a short, checkable list, and one of them, the address of “localhost” from inside an emulator, accounts for a large share of cases.

The checklist, in order

  1. Open the exact URL in the device or emulator's browser. If it does not load there either, the app is innocent; the address, the network, or the server is the problem, and this test isolates which layer to fix.
  2. Fix the host address for emulators: inside the Android emulator, localhost is the emulator itself; the development machine is 10.0.2.2. On the iOS simulator, localhost does reach the host Mac. On a physical device, use the development machine's LAN address and make sure the server binds to it (listens on 0.0.0.0, not just 127.0.0.1) and the firewall allows it.
  3. Check cleartext HTTP: apps built for recent Android and iOS block plain http:// by default. Android needs usesCleartextTraffic enabled (or a network security config) for the development server; iOS needs an App Transport Security exception. In production, the real fix is HTTPS.
  4. Verify the server is actually running and reachable from that network: the backend crashed, listens on a different port, or the phone is on a different Wi-Fi network or a VPN that cannot see the development machine.
  5. Check the certificate on HTTPS endpoints: an expired, self-signed, or mismatched certificate fails the request at the TLS layer with this same generic message; testing the URL in a browser surfaces the certificate problem directly.

How to tell it apart from lookalikes

  1. HTTP error statuses do not throw this. If the code checks response.ok and complains, the request succeeded at network level; a different bug is being reported.
  2. It works on iOS simulator, fails on Android emulator: the 10.0.2.2 host mapping, in almost every case.
  3. It works on the emulator, fails on a real device: the LAN address, the server's bind address, or a firewall, in almost every case.
  4. It fails only in release builds: cleartext rules and missing network configuration differ between debug and release manifests; compare them.

Common questions

Why does fetch not say what went wrong? The web fetch specification surfaces network failures as a generic TypeError by design, partly so pages cannot probe internal network details. React Native inherits that behavior, which is why the checklist approach beats reading the message.

Postman can reach the API, why can't the app? Postman runs on the development machine, where localhost is correct and cleartext rules do not apply. The app runs in a different network context; reproduce from the device or emulator, not from the desktop.

Does CORS cause this in React Native? No. React Native does not enforce CORS; that is a browser rule. A failure that looks like CORS in a mobile app is one of the network causes on this page.

Related errors

Unhandled promise rejection · ERR_CONNECTION_REFUSED · CORS error, explained