Node.js EADDRINUSE — Port Already In Use

EADDRINUSE: Address Already In Use

This error occurs when a Node.js application tries to bind to a network port that is already occupied by another process. It is one of the most common development-time errors.

Finding the Process

macOS / Linux:

# Find process using port 3000
lsof -i :3000
# Output: node  12345 user  22u  IPv6 ...

# Kill the process
kill -9 12345

# One-liner: find and kill
lsof -ti :3000 | xargs kill -9

Windows:

# Find process using port 3000
netstat -ano | findstr :3000

# Kill by PID
taskkill /PID 12345 /F

Common Scenarios

1. Previous instance still running — Crashed server left a zombie process
2. Nodemon restart race condition — New instance starts before old one fully closes
3. Docker port mapping conflict — Same host port mapped by multiple containers
4. Multiple dev servers — Running two projects on the same port

Prevention Strategies

1. Graceful shutdown:

const server = app.listen(3000);

process.on('SIGTERM', () => {
  server.close(() => process.exit(0));
});

process.on('SIGINT', () => {
  server.close(() => process.exit(0));
});

2. Dynamic port fallback:

const server = app.listen(0); // OS assigns random available port
console.log('Listening on port', server.address().port);

3. SO_REUSEADDR:

const server = net.createServer();
server.listen({ port: 3000, exclusive: false });