EADDRINUSE: address already in use — free the port

Hi, it's BlueByte. EADDRINUSE just means something already has the port your app wants — usually a previous run of the app itself that never shut down. Let's find exactly what's holding it, decide whether to stop it or move your app, and cover the case where the port looks free but still won't bind.

What the error means

A server fails to start:

Error: listen EADDRINUSE: address already in use :::3000

The port is taken. Another process — often a previous run of the same app that did not shut down — already holds it, so the new process cannot bind. The fix depends on whether the holder is a stale instance you can kill or a service you actually need, so the first job is to identify it.

Why the port is already taken

Only one process can listen on a given TCP port per interface. You hit EADDRINUSE when:

• An earlier instance is still running — the most common case, especially after a crash or a terminal you closed without stopping the server.
• A different service legitimately uses the same port.
• A crashed process left its socket open, so the port is held until it is released.
• On fast restarts, the previous socket is in TIME_WAIT and the port is not yet free to rebind.

Find exactly what's holding it

Don't kill blindly — find the holder first. On Linux:

ss -ltnp | grep :3000

On macOS:

lsof -nP -iTCP:3000 -sTCP:LISTEN

Both print the PID and the program name. If the name is your own app from a previous run, it is a stale instance; if it is something else you rely on, do not kill it — move your app instead. If nothing is listed as LISTEN but you still cannot bind on a fast restart, the port is in TIME_WAIT — ss -tan | grep :3000 will show it.

Stop the holder, or move your app

1. If it is the stale instance, stop it:

kill 12345          # graceful
kill -9 12345       # only if it ignores the first

2. If the holder is a service you need, run your app on a different port:

PORT=3001 npm start

A real case: a detached dev server

You stop a dev server with Ctrl+C, edit a file, and restart — and it fails with EADDRINUSE :::3000. ss -ltnp | grep :3000 shows a node process from the previous run still listening; closing the terminal earlier had detached it, not stopped it. You kill that PID, confirm ss no longer lists it, and start the server, which binds cleanly. Because this keeps happening on quick restarts, you switch the dev server to reuse the address so a lingering TIME_WAIT socket no longer blocks the rebind.

Confirm the port is yours

Start the server again and confirm it binds:

ss -ltnp | grep :3000   # now shows only your new process

If it starts cleanly and the listener is your app, the port is yours.

Keep it from recurring

Shut servers down cleanly (Ctrl+C, not closing the window), and if a supervisor like systemd, pm2, or Docker keeps respawning the old process, stop it there rather than killing the PID by hand. For fast dev restarts, enable address reuse so the socket does not linger.

How this differs from ECONNREFUSED and EACCES

EADDRINUSE is a local conflict — the port on your own machine is taken. ECONNREFUSED is the opposite end: you tried to connect and nothing was listening. And EACCES on a low port (under 1024) is a permission problem, not a conflict — that port needs elevated privileges. When you hit EADDRINUSE, identify the holder with ss/lsof before you kill anything.