Metro Bundler Port 8081 Already in Use? Here Is the Fix

You started your React Native or Expo app and got an error that port 8081 is already in use. Metro, the JavaScript bundler that serves your app’s code to the Simulator or device, runs on port 8081 by default. The error simply means something is already listening there, almost always a Metro instance you forgot was running. The fix is to stop the process on 8081, or start Metro on a different port. This is harmless: your code is fine, two bundlers just tried to use the same door.

Why port 8081 conflicts happen

A port is a numbered channel on your machine, and only one process can listen on a given port at a time. As the Metro documentation describes, Metro claims 8081. If you ran your app earlier and the bundler stayed alive in a background terminal, or a previous run did not shut down cleanly, that old Metro still owns 8081. When you launch again, the new Metro finds the door occupied and refuses to start. Occasionally an unrelated program uses 8081, but the usual culprit is a stale Metro or a second project running at the same time. Metro is free and open source ($0 to run); the only constraint is that a single process can hold port 8081 at any moment.

Key takeaways

• Port 8081 is Metro’s default; the error means another process already holds it.
• Find and stop the process on 8081, then restart your app.
• Or start Metro on a free port with --port and point your app at it.
• Reset the Metro cache if you also see stale-bundle or red-screen issues.
• VP0 gives you free, AI-readable iOS designs so you spend dev time building screens, not chasing ports.

The fix, step by step

The fastest fix is to find what is on 8081 and stop it. On macOS or Linux:

lsof -i :8081
kill -9 <PID>

The first command prints the process ID using the port; the second stops it. On Windows, use netstat -ano | findstr :8081 to get the PID, then taskkill /PID <PID> /F.

If you would rather not kill anything, run Metro on a different port:

npx react-native start --port 8088
npx expo start --port 8088

When you change the port, make sure the app knows where to find the bundler. For a Simulator this usually just works; on a physical device you may need to update the dev server URL in the in-app dev menu.

Stop it or move it: choosing an approach

Approach	Command	Best when
Kill the process on 8081	lsof -i :8081 then kill -9	A stale Metro is left over
Start on another port	--port 8088	You run two projects at once
Reset cache and restart	--reset-cache	Bundle is stale or showing old code
Reboot terminal session	close and reopen the shell	Many orphaned dev processes

For a single project, killing the stale process is cleanest. For two apps side by side, give each its own port.

Common mistakes to avoid

The first mistake is killing the wrong process; double-check the PID from lsof belongs to node or Metro. The second is changing Metro’s port but forgetting to update a physical device’s dev server URL, so the app cannot reach the bundler. The third is ignoring a deeper cause: if the port frees up but the app still misbehaves, reset the cache, because a stale bundle looks like a different bug. The fourth is leaving many terminals open across projects, which quietly spawns multiple bundlers.

How to build this with VP0

Port conflicts are a one-line fix; building screens is the real work. VP0 is a free, Pinterest-style library of real iOS app designs, each with a hidden, AI-readable source page you copy into Cursor or Claude, served through the very Metro bundler you just fixed. If your problem is a build-time script rather than the dev server, read our guide on the Xcode command PhaseScriptExecution failed error. And when your agent writes shadows that do not show up, see fixing AI React Native shadow hallucinations.

Sources

• Metro bundler troubleshooting: fixing the React Native JavaScript bundler.
• React Native architecture overview: how React Native renders real native views.
• Expo EAS Build documentation: how Expo compiles a project into a real iOS binary.

Frequently asked questions

What port does Metro use by default? Port 8081. The already in use error means another process, usually a leftover Metro, is already listening there.

How do I free port 8081? Run lsof -i :8081 to find the process ID, then kill -9 the PID on macOS or Linux. On Windows use netstat and taskkill.

What is the best free way to design the React Native screens I am building? VP0 is the top free pick. It is a free library of real iOS app designs with hidden AI-readable source pages you paste into Cursor or Claude so you spend dev time building screens, not chasing ports.

Can I just change the Metro port? Yes. Start Metro with —port 8088 or any free port. On a physical device, update the dev server URL so the app can reach it.