React Native Metro Bundler Stuck on “Waiting for Changes”

When Metro sits on “waiting for changes” and never actually rebuilds or serves your app, despite you clearly editing files, it usually means Metro’s file watcher isn’t detecting your changes at all — not that your changes are somehow invalid or being rejected.

The Problem

You start the Metro bundler, it loads once successfully, but after that, editing and saving files does nothing. The terminal just shows:

Waiting on http://localhost:8081

with no new build activity, no errors, and the app on your device or simulator keeps showing the old version of your code no matter how many times you save.

Why It Happens

Metro relies on a file-watching mechanism (usually Watchman on macOS/Linux) to detect changes and trigger a rebuild. The most common reasons this stops working are:

• Watchman itself is in a broken or stale state, often after a machine sleep/wake cycle, a crashed previous session, or a large number of file changes happening very quickly (like a git branch switch)
• Metro’s own cache has become corrupted or is referencing outdated file state, which can happen after switching branches, deleting/renaming files, or an interrupted previous build
• Another Metro instance is already running in the background on the same port, and your terminal is actually looking at a “connected but idle” second instance rather than the one actually serving your device
• The project is inside a symlinked directory, a network drive, or a cloud-synced folder (like Dropbox or OneDrive), all of which can interfere with how file system watchers detect changes

The Fix

First, try the most common fix: clear Metro’s cache and restart it fresh:

npx react-native start --reset-cache

If that doesn’t help, check whether Watchman is in a broken state and reset it:

watchman watch-del-all
watchman shutdown-server

Then restart Metro again after resetting Watchman, so it re-establishes fresh file watches from scratch.

Next, confirm no other Metro process is already running and silently holding the port. Kill anything using port 8081 before starting a fresh instance:

lsof -i :8081
kill -9 <PID>

On Windows, the equivalent is checking with netstat -ano | findstr :8081 and killing the process by its PID via Task Manager or taskkill.

If you suspect the project’s location itself is the problem (cloud-synced folder, network drive, symlink), try moving the project to a plain local directory temporarily, restart Metro, and confirm whether file changes are picked up correctly there — if so, the sync/network layer is interfering with file watching, and you’ll need to either move the project permanently or exclude it from the syncing tool’s watched folders.

As a broader reset, clearing all relevant caches at once often resolves stubborn cases that a single cache clear doesn’t fix:

watchman watch-del-all
rm -rf node_modules
rm -rf /tmp/metro-*
npm install
npx react-native start --reset-cache

Still Not Working?

If none of the above resolves it, check your operating system’s file watcher limits. On Linux especially, the default limit on the number of files a single process can watch (inotify watches) is sometimes too low for large React Native projects with many node_modules files, causing Watchman to silently stop watching new files once the limit is hit. Raising the limit resolves this on Linux:

echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

On macOS, a similar but less commonly hit limit exists for the number of open files a process can hold, which can affect Watchman on very large projects. If you suspect this, check the current limit and raise it temporarily to confirm whether it’s the cause:

ulimit -n
ulimit -n 10240

It’s also worth checking whether antivirus or endpoint security software on Windows is interfering with file system events, which is a surprisingly common and hard-to-diagnose cause of this exact symptom on corporate-managed machines. Some security tools intercept file system calls in ways that prevent Metro’s watcher from receiving change notifications promptly, even though the files themselves are being saved correctly on disk. Temporarily disabling real-time scanning for your project directory, or adding an explicit exclusion for it, is worth testing if you’re on a Windows machine with managed security software and have ruled out every other cause above.

Finally, if you’re using VS Code or another editor with auto-save enabled combined with a very short debounce interval, an extremely rapid sequence of file writes can sometimes overwhelm the watcher’s event queue on lower-powered machines. Increasing the auto-save delay slightly, or saving manually while debugging this specific issue, can help isolate whether write frequency itself is a contributing factor.