SoftwareSideHustles
Debugging

How to Fix "Port Already in Use" (EADDRINUSE) on macOS, Linux and Windows

Find and stop the process holding a port on macOS, Linux and Windows, fix EADDRINUSE in Node.js, Address already in use in Python and BindException in Java, and stop it happening again.

By Software Side Hustles Editorial Team · Published · Updated · 4 min read

Quick answer: another process is already listening on that port — very often an earlier copy of your own server that did not shut down. Find it and stop it: lsof -i :3000 then kill <PID> on macOS/Linux, or netstat -ano | findstr :3000 then taskkill /PID <PID> /F on Windows. Or simply start your app on a different port.

The error in different languages

RuntimeMessage
Node.jsError: listen EADDRINUSE: address already in use :::3000
Python (Linux)OSError: [Errno 98] Address already in use
Python (macOS)OSError: [Errno 48] Address already in use
Python (Windows)OSError: [WinError 10048] Only one usage of each socket address ... is normally permitted
Java / Spring Bootjava.net.BindException: Address already in use / "Web server failed to start. Port 8080 was already in use."
DockerBind for 0.0.0.0:5432 failed: port is already allocated
Golisten tcp :8080: bind: address already in use

:::3000 in the Node.js message means "all IPv6 (and usually IPv4) addresses, port 3000".

How do I find what is using a port on macOS or Linux?

bash
lsof -i :3000
# COMMAND PID USER FD TYPE ... NAME
# node 41235 ada 23u IPv6 ... *:3000 (LISTEN)
kill 41235 # ask it to stop (SIGTERM)
kill -9 41235 # force, only if it ignores the first

Alternatives on Linux:

bash
ss -ltnp | grep :3000 # listening TCP sockets with process names
sudo fuser -k 3000/tcp # find and kill in one step

If lsof shows nothing, the process may belong to another user or root: run it with sudo.

How do I find what is using a port on Windows?

Command Prompt:

bat
netstat -ano | findstr :3000
:: TCP 0.0.0.0:3000 0.0.0.0:0 LISTENING 18404
taskkill /PID 18404 /F

PowerShell:

powershell
Get-NetTCPConnection -LocalPort 3000 | Select-Object LocalPort, State, OwningProcess
Stop-Process -Id 18404

To see which program a PID belongs to: tasklist /FI "PID eq 18404".

Common culprits

  • Your own server is still running in another terminal tab, an IDE run configuration, or as an orphaned child after a crash. Nodemon, npm run dev and IDE debuggers sometimes leave one behind.
  • A Docker container publishes the port. docker ps shows port mappings; docker stop <container> frees it. Local databases are the usual suspects: Postgres on 5432, MySQL on 3306, Redis on 6379.
  • macOS AirPlay Receiver listens on port 5000 (and 7000) on recent macOS versions — which is Flask's default port. Turn off AirPlay Receiver in System Settings → General → AirDrop & Handoff, or run Flask on another port: flask run --port 5001.
  • Another project — two apps that both default to 3000 or 8080.
  • A system service — IIS or "World Wide Web Publishing Service" on port 80 on Windows; Apache or nginx on Linux.

Start on a different port instead

Every framework lets you pick the port, usually via an environment variable:

bash
PORT=3001 npm start # Express apps that read process.env.PORT
next dev -p 3001 # Next.js
vite --port 5174 # Vite
uvicorn main:app --port 8001 # FastAPI
python manage.py runserver 8001 # Django
java -jar app.jar --server.port=8081 # Spring Boot

In your own code, read the port from configuration rather than hard-coding it:

javascript
const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => console.log(`Listening on ${port}`));

Shutting down cleanly so it doesn't happen again

Most "port already in use" errors in development come from servers that do not exit cleanly. Handle termination signals and close the server:

javascript
const server = app.listen(port);
for (const signal of ["SIGINT", "SIGTERM"]) {
process.on(signal, () => server.close(() => process.exit(0)));
}

In Python, run servers inside try/finally or a context manager so sockets close on errors.

TIME_WAIT and SO_REUSEADDR

After a server closes, the operating system can keep the port in a TIME_WAIT state for a short period (typically up to a couple of minutes on Linux). Restarting immediately may fail even though nothing is running. Server frameworks normally set the SO_REUSEADDR socket option to allow rebinding; if you write raw socket code, set it yourself:

python
import socket
s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind(("127.0.0.1", 8000))

Permission denied is a different error

EACCES: permission denied (Node.js) or PermissionError: [Errno 13] when binding means the port is privileged — below 1024 on Unix-like systems — not that it is in use. Use a high port such as 8080 in development and put a reverse proxy in front on 80/443 in production. On Windows, some port ranges are reserved by Hyper-V/WSL; netsh interface ipv4 show excludedportrange protocol=tcp lists them.

Frequently asked questions

Is it safe to kill the process?

Check what it is first. Killing your own stale dev server is fine; killing a database or system service may lose data or break other software.

How do I free a port without knowing the process?

On Linux, sudo fuser -k 3000/tcp. On macOS, kill $(lsof -t -i :3000). On Windows, use the netstat/taskkill pair above.

Why does the error only happen sometimes?

Usually because a previous run did not exit — a crash, a closed terminal or a debugger that kept the process alive — or because the socket is briefly in TIME_WAIT.

Where this skill pays off

Environment problems like this make up a large share of real developer questions, and AI assistants sometimes answer them with commands that are dangerous out of context (kill -9 on whatever matches). Judging whether advice is safe and correct is part of paid AI evaluation work — see how to evaluate AI-generated code.

Cookies on this site

We use essential cookies to run the questionnaire, practice labs and sign-in. With your permission we'd also like to use analytics to understand which pages help people, and advertising cookies to measure our Google Ads. Rejecting never limits any feature. Cookie policy