While developing an Expo or React Native app, you may encounter an error where Hot Module Replacement (HMR) or Fast Refresh stops working with an invalid URL error. This usually appears as `ERR_INVALID_URL` in the Metro HMR client, a WebSocket connection failure, or Fast Refresh silently breaking so that changes require a full reload. These errors appear after upgrading Expo SDK, updating Metro bundler, changing your metro.config.js, running on a different network, or when your development URL contains characters that the HMR WebSocket client cannot parse.

The Error

1TypeError [ERR_INVALID_URL]: Invalid URL
2    at new URL (node:internal/url:775:36)
3    at HMRClient.connect (metro/src/HmrClient.js:84:21)
4
5WebSocket connection to 'ws://undefined:8081/hot' failed
6
7Fast Refresh - Unable to connect to the development server
8
9Error: HMR WebSocket connection error:
10Invalid URL: ws://:8081/hot
11
12Metro HMR error: hostname is not defined

You may also notice that Fast Refresh simply stops working without any visible error. You save a file, nothing updates, and you have to manually reload the app. The Metro terminal may show `Hot Module Replacement is disabled` or no HMR messages at all when you save files.

What Causes This Error

Metro HMR works by opening a WebSocket connection from the app on your device back to the Metro development server. The app constructs a WebSocket URL using the hostname and port of the server that served the JavaScript bundle. When the URL cannot be constructed correctly, HMR fails. The root causes are usually related to how Metro resolves and passes the development server hostname to the HMR client.

• Metro development server hostname is undefined or empty in the HMR client
• Custom metro.config.js overrides that break the internal server URL resolution
• Running Expo on a network where the local IP changes or is not reachable from the device
• A bug in a specific Metro or @expo/metro-config version that incorrectly formats the HMR URL
• Using a tunneling service (ngrok, Expo tunnel) that changes the URL format
• Windows-specific path issues where backslashes in URLs cause ERR_INVALID_URL
• Docker or WSL2 environment where the host IP is not accessible from the development server
• Conflicting metro.config.js plugins or transformers that override the server configuration

Fix 1: Set the Development Server Hostname Explicitly

The most common cause is Metro not knowing the correct hostname to use for the HMR WebSocket URL. You can force the hostname by setting the REACT_NATIVE_PACKAGER_HOSTNAME environment variable or passing it directly when starting Expo.

1# Find your local IP address first
2# macOS/Linux
3ifconfig | grep "inet " | grep -v 127.0.0.1
4
5# Windows
6ipconfig | findstr /i "IPv4"
7
8# Set the hostname and start Expo
9REACT_NATIVE_PACKAGER_HOSTNAME=192.168.1.100 npx expo start
10
11# Or set it in your .env file for persistent use
12# .env
13REACT_NATIVE_PACKAGER_HOSTNAME=192.168.1.100

Replace 192.168.1.100 with your actual local IP address. This tells Metro exactly which hostname to use for the HMR WebSocket connection.

Fix 2: Clear Metro Cache and Restart

Metro caches the server configuration including the HMR URL. If you changed networks, updated metro.config.js, or upgraded Expo, the cached configuration may have the old or broken URL. Clearing all caches forces Metro to rebuild the configuration from scratch.

1# Stop Expo/Metro completely (Ctrl+C)
2
3# Clear all caches
4watchman watch-del-all
5rm -rf node_modules/.cache
6rm -rf $TMPDIR/metro-*
7rm -rf $TMPDIR/haste-map-*
8rm -rf .expo
9
10# Restart with clean cache
11npx expo start --clear

Fix 3: Patch Metro HMR Client for URL Bug

Some Metro versions have a bug where the HMR client receives an undefined hostname and tries to construct an invalid WebSocket URL. If Fixes 1 and 2 do not work, you can patch the Metro HMR client to handle the undefined hostname gracefully. Use patch-package to make this fix survive npm install.

1npm install patch-package --save-dev

Find the HMR client file in node_modules. The exact path depends on your Metro version.

1# Find the HMR client file
2find node_modules/metro -name "HmrClient.js" -o -name "hmrClient.js" 2/dev/null
3
4# Common locations:
5# node_modules/metro/src/HmrClient.js
6# node_modules/metro-runtime/src/modules/HMRClient.js

Open the file and find where the WebSocket URL is constructed. Add a fallback for when the hostname is undefined.

1// Find the line that looks like:
2const wsUrl = `ws://${host}:${port}/hot`;
3
4// Change it to:
5const resolvedHost = host || 'localhost';
6const wsUrl = `ws://${resolvedHost}:${port}/hot`;

After editing, create the patch and add the postinstall script.

1npx patch-package metro
2
3# Or if the file is in metro-runtime:
4npx patch-package metro-runtime

1// package.json
2{
3  "scripts": {
4    "postinstall": "patch-package"
5  }
6}

Fix 4: Patch @expo/metro-config for URL Formatting Bug

In some Expo SDK versions, the @expo/metro-config package formats the development server URL incorrectly. This is different from the Metro HMR client bug. The fix is similar: find the file that constructs the URL, patch it, and use patch-package.

1# Find URL construction in @expo/metro-config
2grep -r "getDevServerUrl\|serverUrl\|hmrUrl" node_modules/@expo/metro-config/build/ --include="*.js" -l
3
4# Patch whichever file has the broken URL logic
5npx patch-package @expo/metro-config

Fix 5: Use Yarn Patch Instead of patch-package

If you use Yarn 2 or above (Berry), you can use the built-in yarn patch command instead of patch-package. This creates patches that are managed by Yarn itself and do not require a postinstall script.

1# Start patching a package
2yarn patch metro
3
4# Yarn opens a temp folder with the package source
5# Edit the HMR client file in the temp folder
6# Then apply the patch:
7yarn patch-commit -s path/to/temp/folder
8
9# The patch is saved in .yarn/patches/ and applied automatically

Fix 6: Switch Connection Type in Expo

Expo supports different connection types for communicating with the development server. If the default LAN connection is causing HMR issues, try switching to localhost or tunnel.

1# Use localhost (device must be on same machine or emulator)
2npx expo start --localhost
3
4# Use tunnel (Expo creates a public URL via ngrok)
5npx expo start --tunnel
6
7# In Expo DevTools (press 'd' in terminal):
8# Switch between LAN, Local, and Tunnel

Fix 7: Windows-Specific Path Fix

On Windows, file paths use backslashes which can leak into URLs and cause ERR_INVALID_URL. If you are on Windows and see this error, the URL may contain backslashes like `ws://C:\Users\...` instead of forward slashes.

1# Option 1: Use WSL2 for development
2wsl
3cd /mnt/c/your/project
4npx expo start
5
6# Option 2: Set REACT_NATIVE_PACKAGER_HOSTNAME to avoid path-based URLs
7set REACT_NATIVE_PACKAGER_HOSTNAME=127.0.0.1
8npx expo start
9
10# Option 3: Use Git Bash or PowerShell instead of CMD
11# CMD has more issues with path formatting in environment variables

Fix 8: Docker and WSL2 Network Fix

In Docker containers or WSL2, the development server runs on a different network than the host machine. The device cannot reach the Metro server using the container internal IP. You need to expose the correct host IP to Metro.

1# Docker: expose Metro port and set hostname to host IP
2docker run -p 8081:8081 -e REACT_NATIVE_PACKAGER_HOSTNAME=host.docker.internal your-app
3
4# docker-compose.yml
5services:
6  app:
7    build: .
8    ports:
9      - "8081:8081"
10    environment:
11      - REACT_NATIVE_PACKAGER_HOSTNAME=host.docker.internal
12
13# WSL2: find the Windows host IP
14cat /etc/resolv.conf | grep nameserver | awk '{print $2}'
15# Use that IP as REACT_NATIVE_PACKAGER_HOSTNAME
16export REACT_NATIVE_PACKAGER_HOSTNAME=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
17npx expo start

Quick Diagnosis Checklist

• Check if the error shows undefined or empty hostname in the WebSocket URL
• Try setting REACT_NATIVE_PACKAGER_HOSTNAME to your local IP address
• Clear all caches: .expo, metro temp files, watchman, node_modules/.cache
• Restart Metro with npx expo start --clear
• Check if your device and development machine are on the same network
• Try switching connection type: --localhost, --tunnel, or LAN in Expo DevTools
• On Windows: check for backslashes in URL errors and try WSL2 or Git Bash
• In Docker or WSL2: expose port 8081 and set hostname to host.docker.internal
• If a specific Metro version is broken: patch the HMR client with patch-package
• Update Expo SDK and Metro: npx expo install expo@latest && npx expo install --fix

Final Working Commands

1# Quick fix: set hostname and clear cache
2watchman watch-del-all
3rm -rf .expo node_modules/.cache $TMPDIR/metro-*
4
5REACT_NATIVE_PACKAGER_HOSTNAME=$(ifconfig | grep 'inet ' | grep -v 127.0.0.1 | head -1 | awk '{print $2}') npx expo start --clear

1# Windows equivalent
2for /f "tokens=2 delims=:" %%a in ('ipconfig ^| findstr /i "IPv4" ^| findstr /v "127.0.0.1"') do set REACT_NATIVE_PACKAGER_HOSTNAME=%%a
3npx expo start --clear

Official-Style Error Explanation

Expo Metro HMR invalid URL errors occur when the Metro development server cannot construct a valid WebSocket URL for the Hot Module Replacement client. Metro HMR works by opening a WebSocket connection from the app on the device back to the development server using the server hostname and port. When the hostname is undefined, empty, or contains invalid characters like Windows backslashes, the URL constructor throws ERR_INVALID_URL and HMR fails. The most common causes are network configuration issues where Metro cannot determine its own hostname, specific Metro or @expo/metro-config version bugs that format the URL incorrectly, Windows path characters leaking into URLs, and Docker or WSL2 environments where the internal network IP is not reachable from the device. The fix is usually to set REACT_NATIVE_PACKAGER_HOSTNAME to your local IP address and clear all Metro caches. For version-specific bugs, patching the Metro HMR client with patch-package or yarn patch provides a reliable workaround until the upstream fix is released.