Every Node.js developer has encountered that infamous error message at least once: Error: listen EADDRINUSE: address already in use.

When you first see this error, you might think “What went wrong?” and feel a bit panicked. The truth is, this error happens more often than you’d think, and the solution is actually pretty straightforward. Today, let’s walk through why this error occurs and how to fix it step by step.

 

What is the EADDRINUSE Error?

EADDRINUSE stands for “Error: Address Already in Use.” This error occurs when your Node.js application tries to bind to a port that’s already being used by another process.

Common Scenarios

• A previously launched Node.js server didn’t shut down properly
• Another application is using the same port
• You used Ctrl+Z to background a process (instead of Ctrl+C to terminate it)
• Trying to run multiple servers simultaneously in your development environment

The actual error message looks like this:

Error: listen EADDRINUSE: address already in use :::3000
    at Server.setupListenHandle [as _listen2] (node:net:1330:16)
    at listenInCluster (node:net:1378:12)
    at Server.listen (node:net:1465:7)

 

 

Diagnosing the Issue: Finding Which Process is Using the Port

To solve the problem, you first need to identify which process is occupying the port. The method varies depending on your operating system.

Port Check Commands by Operating System

Operating System	Command	Description
Linux/macOS	lsof -i :3000	Find process using port 3000
Linux/macOS	netstat -anp | grep :3000	Check port using netstat
Windows	netstat -ano | findstr :3000	Check port on Windows
Windows	tasklist /fi "PID eq [PID]"	Get process info for specific PID

Checking on Linux/macOS

The most commonly used method is the lsof command:

# Check which process is using port 3000
sudo lsof -i :3000

# Example output
COMMAND  PID   USER   FD   TYPE   DEVICE SIZE/OFF NODE NAME
node    12345  user   23u  IPv6  0x12345      0t0  TCP *:3000 (LISTEN)

You can also use the netstat command:

# Check port 3000 in LISTEN state
netstat -anp | grep :3000 | grep LISTEN

Checking on Windows

On Windows, use a combination of netstat and tasklist:

# Step 1: Find the PID of the process using the port
netstat -ano | findstr :3000

# Step 2: Get process info using PID (example: PID 12345)
tasklist /fi "PID eq 12345"

 

 

Solution 1: Terminate the Process

Once you’ve identified the process using the port, you need to terminate it.

Terminating Process on Linux/macOS

After finding the PID, use the kill command to terminate the process:

# Try graceful termination first
kill 12345

# Force kill if the above doesn't work
kill -9 12345

# Or kill all node processes
killall node

Terminating Process on Windows

Windows offers several ways to terminate processes:

# Kill by PID from command prompt
taskkill /PID 12345 /F

# Kill all Node.js processes
taskkill /F /IM node.exe

You can also use Task Manager. Press Ctrl+Shift+Esc to open Task Manager, go to the “Details” tab, find the node.exe process, and click “End task.”

 

 

Solution 2: Easy Fix (Using kill-port Package)

If typing complex commands every time feels tedious, using the kill-port npm package is much more convenient.

Using the kill-port Package

# One-time use with npx (no installation needed)
npx kill-port 3000

# Kill multiple ports simultaneously
npx kill-port 3000 3001 8080

# Install globally and use
npm install -g kill-port
kill-port 3000

This package works identically across Windows, macOS, and Linux, making it particularly useful in cross-platform development environments.

 

 

Solution 3: Change the Port

Sometimes using a different port is a better solution than terminating processes.

Changing Port in Express.js

const express = require('express');
const app = express();

// Set port via environment variable or use default
const PORT = process.env.PORT || 3001; // Use 3001 instead of 3000

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Dynamic Port Assignment

You can configure Node.js to automatically find an available port:

const express = require('express');
const app = express();

// Setting port to 0 automatically assigns an available port
const server = app.listen(0, () => {
  const port = server.address().port;
  console.log(`Server running on port ${port}`);
});

Managing Ports with Environment Variables

You can configure different ports for development, testing, and production environments:

# Linux/macOS
export PORT=5000
node app.js

# Windows CMD
set PORT=5000
node app.js

# Windows PowerShell
$env:PORT=5000
node app.js

 

 

While the EADDRINUSE error might seem intimidating at first, it’s totally manageable once you understand the cause and solutions.

The key is to identify which process is using the port and either terminate that process appropriately or use a different port. Having the kill-port package or proper error handling in place makes dealing with this issue much smoother during development.

Most importantly, always use the correct method (Ctrl+C) to terminate servers during development, and use proper process management tools in production environments. Building these habits will significantly reduce EADDRINUSE errors in your workflow.