This error occurs when you try to start a Node.js server on a port that is already occupied by another process. The system refuses to bind to the port because another application is already listening on it.
The EADDRINUSE (Error ADDRess In USE) error is thrown by the Node.js runtime when your application attempts to listen on a TCP port that is already bound to another process. This is a system-level error that prevents multiple processes from listening on the same network address and port combination. When you start a Node.js server using `server.listen()` or `app.listen()`, the operating system tries to reserve that port for your application. If another process has already claimed that port, the OS denies the request and Node.js throws this error. This is a common issue in development environments where developers frequently start and stop servers, sometimes leaving zombie processes running in the background.
First, identify which process is occupying the port. The commands differ by operating system.
On macOS/Linux:
lsof -i :3000This will show output like:
COMMAND PID USER FD TYPE DEVICE SIZE/OFF NODE NAME
node 12345 user 23u IPv6 0x... 0t0 TCP *:3000 (LISTEN)Note the PID (Process ID) shown in the output.
On Windows (Command Prompt or PowerShell):
netstat -ano | findstr :3000This shows output like:
TCP 0.0.0.0:3000 0.0.0.0:0 LISTENING 12345The last number (12345) is the PID.
Once you have the PID, terminate the process.
On macOS/Linux:
kill -9 12345Or kill all Node.js processes on that port:
lsof -ti :3000 | xargs kill -9On Windows (as Administrator):
taskkill /PID 12345 /FOr kill all Node.js processes:
taskkill /F /IM node.exeAfter killing the process, try starting your server again.
Install the kill-port package for a simple, cross-platform way to free up ports:
npm install -g kill-portThen use it to kill the process on a specific port:
kill-port 3000Or use it as a dev dependency and add to your package.json scripts:
{
"scripts": {
"predev": "kill-port 3000",
"dev": "nodemon server.js"
}
}This automatically frees the port before starting your development server.
If you cannot free up the port or prefer to use a different one, modify your application to listen on an alternative port.
Using environment variables (recommended):
const PORT = process.env.PORT || 3001;
app.listen(PORT, () => {
console.log(`Server running on port ${PORT}`);
});Then start your app with:
PORT=3001 npm startHardcoded alternative (not recommended for production):
app.listen(3001, () => {
console.log('Server running on port 3001');
});This allows your application to run without conflicting with the process on port 3000.
Implement proper error handling to detect and respond to port conflicts gracefully:
const server = app.listen(PORT, () => {
console.log(`Server running on port ${PORT}`);
});
server.on('error', (err) => {
if (err.code === 'EADDRINUSE') {
console.error(`Port ${PORT} is already in use`);
console.log('Please kill the process or use a different port');
process.exit(1);
} else {
throw err;
}
});Or try alternative ports automatically:
function startServer(port) {
const server = app.listen(port, () => {
console.log(`Server running on port ${port}`);
});
server.on('error', (err) => {
if (err.code === 'EADDRINUSE') {
console.log(`Port ${port} busy, trying ${port + 1}`);
startServer(port + 1);
}
});
}
startServer(3000);Port Binding and TIME_WAIT State:
When a TCP connection closes, the port may remain in a TIME_WAIT state for 30-120 seconds depending on your OS. This prevents immediate reuse to ensure all packets from the previous connection are handled. If you're repeatedly stopping and starting your server, you might encounter this. The SO_REUSEADDR socket option can help, but Node.js HTTP servers don't expose this directly.
Docker and Port Mapping:
If running Node.js in Docker, ensure you're mapping ports correctly with -p flags and that the container's internal port doesn't conflict with other containers. Also verify that your host machine's port is available.
Multiple Server Instances in Code:
Ensure your application code doesn't accidentally create multiple HTTP server instances. This can happen when using file watchers or when importing server creation code multiple times without proper singleton patterns.
Development Tool Conflicts:
IDEs like VS Code with debugger configurations or tools like Webpack Dev Server may occupy common ports (3000, 8080). Check your IDE's running processes and terminal sessions.
Production Considerations:
In production, use process managers like PM2, systemd, or Docker that properly handle process lifecycle and prevent orphaned processes. Always use environment variables for port configuration to avoid hardcoded conflicts.
Alternative: detect-port package:
The detect-port npm package can programmatically find an available port:
const detect = require('detect-port');
detect(3000).then(port => {
if (port === 3000) {
console.log('Port 3000 is available');
} else {
console.log(`Port 3000 is in use, using ${port} instead`);
}
app.listen(port);
});Error: Listener already called (once event already fired)
EventEmitter listener already called with once()
Error: EACCES: permission denied, open '/root/file.txt'
EACCES: permission denied
Error: Invalid encoding specified (stream encoding not supported)
How to fix Invalid encoding error in Node.js readable streams
Error: EINVAL: invalid argument, open
EINVAL: invalid argument, open
TypeError: readableLength must be a positive integer (stream config)
TypeError: readableLength must be a positive integer in Node.js streams