Troubleshooting Expo Go Connection Failures: Resolving Metro Bundler Timeouts

The Connection Gap

When starting an Expo project, the most common point of failure is the handshake between the mobile device running the Expo Go app and the Metro bundler (the JavaScript bundler for React Native) running on your development machine. This typically manifests as a Network response timed out or Could not connect to development server error after scanning the QR code.

The core issue is almost always a networking barrier—either a software firewall, a hardware subnet mismatch, or a network configuration that prevents the mobile device from reaching the host machine's local IP address on port 8081.

Diagnostic Matrix

Symptom	Likely Cause	Primary Diagnostic
Immediate timeout on QR scan	Network Isolation / Wrong Subnet	Ping host IP from mobile browser
Hangs at 0% or 1% loading	Firewall blocking Port 8081	Check OS inbound rules
Version mismatch error	SDK/Expo Go incompatibility	Compare project package.json with app version
Works on some devices, not others	Device-specific VPN or Proxy	Disable mobile VPN/Private Relay

Step-by-Step Connection Audit

1. Verify Network Alignment

For LAN mode to work, the mobile device and the computer must be on the same local area network (LAN). Many corporate or public Wi-Fi networks use AP Isolation (Access Point Isolation), which allows devices to access the internet but prevents them from communicating with each other.

• Check that both devices are connected to the same SSID.
• Verify your host IP: Run ipconfig (Windows) or ifconfig (macOS/Linux) to find your local IP (e.g., 192.168.1.15).
• The Browser Test: Open the mobile browser on your device and type http://[YOUR-HOST-IP]:8081/status. If the page doesn't load, the network is blocking the path.

2. Configure Host Firewall Rules

Even if the network allows the connection, your operating system may block incoming requests to port 8081.

• Windows: Ensure the "Node.js JavaScript Runtime" is allowed through the Windows Defender Firewall for "Private" networks.
• macOS: Check System Settings > Network > Firewall. If enabled, ensure the terminal or Node.js is permitted to receive incoming connections.

3. Validate SDK and App Versions

Expo Go is updated frequently. If your project uses an older SDK version that is no longer supported by the current Expo Go app version from the App Store or Play Store, the connection may fail or crash immediately after loading.

Check your package.json for the expo version. If you are using a version significantly older than the current release, consider upgrading the SDK or using a Development Build instead of Expo Go.

Applying the Fixes

Option A: The LAN Fix (Preferred Performance)

If the browser test failed due to firewall issues, open the port and restart the server:

# Run this in your project root on the host machine
npx expo start --lan

Risk: Exposing port 8081 on a public network can be a security risk. Only use LAN mode on trusted private networks.

Option B: The Tunnel Fix (Bypass Network Restrictions)

If you are on a restricted network (like a corporate office or university) where you cannot change firewall settings or disable AP isolation, use a tunnel. This routes traffic through an external proxy (ngrok), bypassing local network barriers.

# Run this in your project root on the host machine
npx expo start --tunnel

Limitations: Tunnel mode is significantly slower than LAN mode. Bundle loading times increase because the JavaScript bundle must travel to a remote server and back to your device.

Verification and Rollback

To verify the fix, scan the new QR code. The Metro bundler terminal should show a progress percentage (0%... 100%) as the bundle is transferred.

Rollback: If you switched to --tunnel and experience extreme lag or stability issues, stop the process (Ctrl+C), ensure you are on a private Wi-Fi, and revert to npx expo start --lan.

Escalation Criteria

If the following conditions are met and the connection still fails, the issue is likely outside of network configuration:

• The mobile browser can successfully reach http://[HOST-IP]:8081/status.
• The --tunnel flag also fails to connect.
• The Expo Go app is updated to the latest version.

In these cases, check for node_modules corruption by deleting the folder and package-lock.json, then running npm install again.