How to Fix EADDRINUSE: Port Already in Use Error in Node.js

Understanding the Node.js EADDRINUSE Error Exception

The EADDRINUSE error string is an acronym for Error Address In Use. At the operating system networking layer, every network service registers a combination of an IP address and a TCP/UDP port number to listen for incoming packet traffic.

When your application calls app.listen(3000) or server.listen(5000), the OS kernel checks the network socket binding table:

• Port Available: The kernel allocates the requested port to the calling Process ID (PID) and transitions the socket state to LISTEN.
• Port Occupied: If another process already holds the binding lock on that port, the kernel rejects the socket request, triggering an asynchronous EADDRINUSE exception in the Node.js event loop.

Common triggers include running multiple instances of a local server across different terminal tabs, background task runners hanging after unhandled promise rejections, or hot-reload bundlers failing to release port locks during abnormal process restarts.

Fixing EADDRINUSE on Windows using PowerShell

On Windows 11 and Windows 10, PowerShell provides native cmdlets to inspect active TCP socket connections and terminate specific target PIDs without needing third-party administrative utilities.

Step 1: Inspect Active TCP Connections by Port Number

To locate the exact Process ID holding the port lock (for example, port 3000), execute the native Get-NetTCPConnection cmdlet:

# Query active TCP connections listening on port 3000
Get-NetTCPConnection -LocalPort 3000 | Select-Object LocalAddress, LocalPort, OwningProcess, State

This command outputs a formatted table listing the local address, port, socket state (such as Listen), and the numeric OwningProcess ID (PID).

Step 2: Terminate the Conflicting Process ID

Once you identify the numeric PID (for example, PID 14832), stop the process safely using the Stop-Process cmdlet:

# Terminate the target process using its Process ID
Stop-Process -Id 14832 -Force

One-Line PowerShell Command for Instant Port Cleanup

You can combine connection lookup and process termination into a single, automated one-line PowerShell command:

# Find and terminate any process listening on port 3000
Get-NetTCPConnection -LocalPort 3000 -ErrorAction SilentlyContinue | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }

Fixing EADDRINUSE on Windows using Command Prompt (cmd.exe)

If you are operating inside a standard Windows Command Prompt terminal, you can use legacy network diagnostic utilities (`netstat` and `taskkill`).

Step 1: Locate the Process ID via Netstat

Execute `netstat` with network listing options and filter for the target port number:

# Find active listeners on port 3000
netstat -ano | findstr :3000

The output displays active network connections. The final column in the output table contains the numerical Process ID (PID).

Step 2: Kill the Process using Taskkill

Pass the extracted PID to the `taskkill` utility using the force flag (`/F`):

# Forcefully terminate process ID 14832
taskkill /PID 14832 /F

Fixing EADDRINUSE on Linux, macOS, and WSL2

On Unix-based operating systems (including Ubuntu, Debian, macOS, and Windows Subsystem for Linux), POSIX utilities provide fast ways to release bound ports.

Method 1: Using LSOF (List Open Files)

The `lsof` utility inspects open file descriptors and active network sockets across all running processes:

# List process details listening on TCP port 3000
lsof -i :3000

This returns details including the process name (such as `node`), PID, user, and file type. Terminate the process using the standard kill command:

# Send SIGKILL signal to process ID 14832
kill -9 14832

Method 2: Using Fuser for Direct Port Termination

The `fuser` utility accesses process IDs using specific files, sockets, or file systems:

# Check process using port 3000
sudo fuser 3000/tcp

# Kill process listening on port 3000 directly in one command
sudo fuser -k 3000/tcp

Cross-Platform Port Cleanup via NPX (Kill-Port Utility)

If you work in a cross-platform environment across Windows, Linux, and macOS, installing platform-specific commands in npm scripts can be tedious. The open-source `kill-port` CLI utility provides a uniform command interface.

Run `npx kill-port` directly from your terminal without pre-installing a global package:

# Terminate any process bound to port 3000 across any OS
npx kill-port 3000

# Terminate multiple port bindings simultaneously
npx kill-port 3000 5000 8080

Integrating Port Cleanup into Package.json Scripts

You can prepend `kill-port` to your development scripts in `package.json` to ensure clean port initialization prior to starting local server runtimes:

{
  "scripts": {
    "predev": "npx kill-port 3000",
    "dev": "node server.js"
  }
}

Programmatic Graceful Shutdown in Node.js & Express

Rather than relying on manual process killing after a crash, configuring graceful process handling in your server source code ensures that Node.js closes active TCP server sockets cleanly when receiving termination signals (`SIGINT` or `SIGTERM`).

Implementing Signal Interceptors for Server Socket Cleanup

Add process signal handlers to your main server entry point (`server.js` or `app.js`):

const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;

app.get('/', (req, res) => {
    res.send('Server is running smoothly');
});

const server = app.listen(PORT, () => {
    console.log(`Server listening on http://localhost:${PORT}`);
});

// Function to handle clean server shutdown
const gracefulShutdown = (signal) => {
    console.log(`Received ${signal}. Closing HTTP server socket...`);
    
    server.close(() => {
        console.log('HTTP server closed successfully. Releasing port lock.');
        process.exit(0);
    });

    // Force exit if server shutdown hangs for over 5 seconds
    setTimeout(() => {
        console.error('Forced shutdown execution due to hung connections.');
        process.exit(1);
    }, 5000);
};

// Listen for process termination signals (Ctrl+C and process kill calls)
process.on('SIGINT', () => gracefulShutdown('SIGINT'));
process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));

Official Technical References & Documentation

For further technical specifications on networking sockets, Node.js net modules, and operating system process commands:

• Node.js Net Module Documentation: https://nodejs.org/api/net.html
• Microsoft Windows Taskkill Command Reference: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/taskkill