Fix: address already in use (EADDRINUSE)

Error: listen EADDRINUSE: address already in use :::3000
OSError: [Errno 98] Address already in use
bind: address already in use
nginx: [emerg] bind() to 0.0.0.0:80 failed (98: Address already in use)

Only one program can listen on a given address and port at a time. Yours asked the kernel for a port that another process already holds, so the bind call failed. The fix is always the same: find who holds the port, then stop it or move one of them.

Find the process holding the port

# Linux
sudo ss -ltnp 'sport = :3000'
# LISTEN 0 511 *:3000 *:* users:(("node",pid=48213,fd=20))

# macOS and Linux
sudo lsof -nP -iTCP:3000 -sTCP:LISTEN
# COMMAND   PID  USER   FD   TYPE  NODE NAME
# node    48213 alice   20u  IPv6  TCP  *:3000 (LISTEN)

# Windows
netstat -ano | findstr :3000

Cause 1: a previous copy of your own application

A dev server that did not shut down, a terminal tab you forgot, a debugger session still attached, or a process a file watcher such as nodemon left behind. Stop it politely first and only force it if it ignores you.

kill 48213            # SIGTERM, lets it clean up
sleep 2
kill -9 48213         # only if it is still there

# one-liner for the port you know
kill "$(lsof -t -iTCP:3000 -sTCP:LISTEN)"

Careful: check the process name before killing. A PID from lsof on port 5432 is probably your database, and killing it with -9 can lose in-flight writes.

Cause 2: a system service or container owns the port

Port 80 or 443 is usually Apache or nginx, 5432 PostgreSQL, 3306 MySQL, 6379 Redis, 8080 a Java app or a proxy. Docker publishes ports through docker-proxy and the container keeps running after your terminal closes.

sudo systemctl stop nginx          # stop the service, or change its port in its config
docker ps --format '{{.Names}}\t{{.Ports}}'
docker stop <container>

Cause 3: the port is in TIME_WAIT after a restart

Right after stopping a server, the kernel keeps the socket in TIME_WAIT for a minute. Programs that set SO_REUSEADDR (most frameworks do by default; Python’s socketserver needs allow_reuse_address = True) can rebind immediately. If you hit it in tests or scripts, wait a few seconds or let the server choose a free port (port 0) and read back which one it got.

Cause 4: wrong address, same port

127.0.0.1:3000 and 0.0.0.0:3000 conflict with each other, and on Linux an IPv6 :::3000 listener usually covers IPv4 too. Two services cannot share a port by using different host names on the same machine. Put one of them on another port, or front both with a reverse proxy that routes by host name.

PORT=3001 npm start            # most Node apps read PORT
flask run --port 5001
uvicorn app:app --port 8001

Check that it is fixed

sudo ss -ltnp 'sport = :3000'      # empty, or shows only your new process
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3000/

When it is not what you think

• EACCES or Permission denied on bind means a privileged port below 1024 without root, not a busy port.
• EADDRNOTAVAIL means the IP address you asked to bind to does not exist on this machine, for example a config copied from another server.
• If ss and lsof show nothing but bind still fails, you may be inside a container or network namespace that differs from your shell, or a firewall or VPN client is reserving a port range (Windows Hyper-V does this: netsh interface ipv4 show excludedportrange protocol=tcp).
• A port that frees itself only after a minute is TIME_WAIT, not a stuck process.

Official documentation

• ss(8) manual page
• Node.js: server.listen and EADDRINUSE
• socket(7): SO_REUSEADDR