How to Fix EADDRINUSE: address already in use

What is the EADDRINUSE Error?

The EADDRINUSE error occurs when your application tries to listen on a port that another process is already using. You will see an error message like:

Error: listen EADDRINUSE: address already in use :::3000
    at Server.setupListenHandle [as _setupListenHandle] (net.js:1331:16)
    at listenInCluster (net.js:1379:12)

This is one of the most common errors developers encounter when working with Node.js, Express, Next.js, Vite, Django, or any web server. It means the port your server needs (e.g., 3000, 8080, 5000) is occupied by another process.

Common Causes

• Crashed dev server that did not release the port before exiting
• Multiple terminal tabs running the same server
• Background process (zombie) holding the port
• Another application using the same default port
• Docker container mapping to the same host port
• Hot reload that failed to restart cleanly

Quick Fix with portrm (30 Seconds)

The fastest way to fix EADDRINUSE is with portrm, a Rust CLI that identifies the process, checks safety, and kills it gracefully:

$ ptrm fix 3000

  Port 3000 in use
  Node.js (PID 84921) - Next.js dev server
  Running for 2h 15m - 14.2 MB memory
  SAFE - dev server, safe to kill

  Fix port 3000? [Y/n] Y

  Killed PID 84921 (SIGTERM)
  Port 3000 is now free

To skip confirmation and auto-restart your dev server:

$ ptrm fix 3000 -y --run "npm run dev"

Install portrm:

$ npm install -g portrm     # npm
$ brew install abhishekayu/tap/portrm  # Homebrew
$ npx portrm fix 3000       # or try without installing

Manual Fix

macOS / Linux

Step 1: Find the process using the port:

$ lsof -i :3000
COMMAND  PID    USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
node    84921  user   23u  IPv6 0x...  0t0      TCP *:3000 (LISTEN)

Step 2: Kill the process using its PID:

$ kill -9 84921

Warning: kill -9 sends SIGKILL, which forces immediate termination without allowing cleanup. This can cause data loss for databases. Use kill 84921 (SIGTERM) first, or use portrm which handles this automatically.

Windows

Step 1: Find the process:

> netstat -ano | findstr :3000
  TCP    0.0.0.0:3000    0.0.0.0:0    LISTENING    84921

Step 2: Kill the process:

> taskkill /PID 84921 /F

How to Prevent EADDRINUSE

• Use ptrm preflight 3000 before starting your server to check if the port is free
• Add a .ptrm.toml config to your project with ptrm init for consistent port assignments
• Use ptrm watch 3000 to auto-recover from crashes
• Handle SIGTERM and SIGINT in your application to release ports on shutdown
• Use a process manager like ptrm up instead of manual terminal commands

Framework-Specific Fixes

Next.js

$ ptrm fix 3000 --run "npx next dev"
# or manually: kill the process on port 3000, then restart

Express / Node.js

$ ptrm fix 3000 --run "node server.js"

Vite / React

$ ptrm fix 5173 --run "npm run dev"

Django / Python

$ ptrm fix 8000 --run "python manage.py runserver"