Error: listen EADDRINUSE: address already in use :::3000
ID: node/eaddrinuse-port
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| 20 | active | — | — | — |
| 20 | active | — | — | — |
Root Cause
EADDRINUSE means another process is already listening on the requested port. This is almost always resolvable by identifying and stopping the conflicting process or choosing a different port. It is one of the most common and straightforward Node.js errors.
genericWorkarounds
-
95% success Find and kill the specific process using the port
Run 'lsof -i :3000' (replace 3000 with the port from the error) to identify the PID. Then run 'kill <PID>'. If the process does not terminate, use 'kill -9 <PID>'. Alternative: 'fuser -k 3000/tcp' to kill the process directly.
-
85% success Use a port-finding library to automatically select an available port
Install 'detect-port' or 'portfinder': 'npm install detect-port'. In code: const detect = require('detect-port'); const port = await detect(3000); // returns 3000 if free, or next available port. -
80% success Add graceful shutdown to prevent orphaned processes
Handle SIGTERM and SIGINT in your Node process: process.on('SIGTERM', () => { server.close(() => process.exit(0)); }); This ensures the port is released when the process is stopped, preventing stale listeners.
Dead Ends
Common approaches that don't work:
-
Binding to port 0 to let the OS assign a random port
70% fail
While technically valid, port 0 makes the service unreachable at a predictable address. Other services, reverse proxies, and clients that depend on a known port will break. This avoids the symptom but creates a different problem.
-
Running 'killall node' to kill all Node processes
55% fail
This kills every Node process on the system, including unrelated ones such as build watchers, other services, or VS Code extensions. It is a blunt instrument that causes collateral damage and does not address the root cause of why a stale process held the port.