EADDRINUSE Address Already in Use: Find and Stop the Process

EADDRINUSE means Node asked the operating system for a listening socket on a port, and something on the same machine already holds that address and port. The Node.js errors reference describes it as a failed attempt to bind a net, http or https server because another server already occupies the address. There are two fixes: stop whatever owns the port, or start your app on a different one.

Most of the time the owner is an earlier copy of your own app. A dev server in a forgotten terminal tab, a file watcher that restarted but left its child alive, or a container still publishing the port. The commands below find it on macOS, Linux and Windows. The sections after that cover switching ports and handling the error in code so it stops crashing your process.

What the error looks like and why it happens#

The full crash usually reads like this (line numbers vary by Node version):

node:events:497
      throw er; // Unhandled 'error' event
      ^

Error: listen EADDRINUSE: address already in use :::3000
    at Server.setupListenHandle [as _listen2] (node:net:1908:16)
    at listenInCluster (node:net:1965:12)
    at Server.listen (node:net:2067:7)
Emitted 'error' event on Server instance at:
    at emitErrorNT (node:net:1944:8)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21) {
  code: 'EADDRINUSE',
  errno: -98,
  syscall: 'listen',
  address: '::',
  port: 3000
}

Three fields on that error object do the diagnosing for you. syscall: 'listen' says it failed while setting up a server, not while connecting out. address is the interface Node tried to bind. :: is the unspecified IPv6 address, which Node uses when you don't pass a host, and on most systems it covers IPv4 as well. port is the number that's taken. Don't key logic off the numeric errno value. Compare err.code === 'EADDRINUSE' instead.

The process dies because server.listen() emitted an 'error' event and nothing was subscribed to it. That's what the Unhandled 'error' event line at the top means. The port conflict is the cause, but the missing handler is what turned it into a crash.

One detail saves a lot of head-scratching. Node sets SO_REUSEADDR on its sockets, so connections lingering in TIME_WAIT from a previous run don't normally trigger this error. A live listener does. If you see EADDRINUSE, assume a real process is sitting on the port and go find it.

Find and stop the process on macOS and Linux#

lsof works on both systems and prints the command name, PID and user on one line. Replace 3000 with your port:

lsof -nP -iTCP:3000 -sTCP:LISTEN

COMMAND   PID  USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
node    48213  indra  23u  IPv6  0x1a2b      0t0  TCP *:3000 (LISTEN)

-nP skips DNS and service-name lookups so the output is fast and shows raw numbers. -sTCP:LISTEN drops client connections to that port, which is what you want, because only the listener matters. If nothing prints, the port is free as far as this host can see, and you should check the gotchas section for the Docker, WSL and IPv4 versus IPv6 cases.

On Linux, ss is usually faster and installed by default:

ss -ltnp | grep ':3000'

LISTEN 0 511  *:3000  *:*  users:(("node",pid=48213,fd=23))

The p flag only shows PIDs for processes you own. Prefix the command with sudo if the users part is missing. The ss man page covers the filter syntax if you'd rather match a port without grep.

Before you kill anything, check what the PID actually is. node could be any Node app on the machine:

ps -p 48213 -o pid=,args=

Now stop it. Start with a plain kill, which sends SIGTERM and lets the process shut down cleanly:

kill 48213

Re-run the lsof or ss command. If the line is gone, start your app and you're done. If the process is still there after a few seconds, it's ignoring SIGTERM, and you can escalate:

kill -9 48213

Treat kill -9 as the last resort. It skips every cleanup handler, so a database writer or a test runner can leave lock files or half-written state behind. Confirm the PID really is the stray server before you send it.

A one-liner you'll see everywhere is kill $(lsof -t -i :3000). It works, but -t prints every PID touching the port, including clients connected to it, so on a busy port it can kill more than you intended. I'd look at the full list first and kill by number.

Find and stop the process on Windows#

In Command Prompt, netstat lists listeners with their PIDs and findstr narrows the output to your port:

netstat -ano | findstr :3000

TCP    0.0.0.0:3000    0.0.0.0:0    LISTENING    17340
TCP    [::]:3000       [::]:0       LISTENING    17340

The last column is the PID. To see what it is before you kill it:

tasklist /FI "PID eq 17340"

Then stop it:

taskkill /PID 17340 /F

/F forces termination. Without it, taskkill only asks the process to close, and a console program such as node.exe usually ignores the request, so in practice you need the flag. Re-run the netstat line to confirm the LISTENING entry is gone.

In PowerShell the same steps give you the process name directly:

Get-NetTCPConnection -LocalPort 3000 -State Listen | Select-Object OwningProcess
Get-Process -Id 17340
Stop-Process -Id 17340

If the owning process is svchost.exe or System, a Windows service or a reserved port range holds it. Don't kill those. Switch ports instead.

Pick another port instead#

Sometimes killing isn't an option. The other process is a colleague's service in a shared VM, a system daemon, or a container you actually need. Then move your app.

Read the port from the environment with a sensible default:

const http = require('node:http');

const port = Number(process.env.PORT) || 3000;

http.createServer((req, res) => {
  res.end('ok');
}).listen(port, () => {
  console.log(`listening on ${port}`);
});

PORT=3001 node server.js

In Windows Command Prompt, set the variable on its own line first:

set PORT=3001
node server.js

Most framework dev servers read PORT or take a port option on the command line. Check your dev command's --help output rather than guessing.

If you don't care which port you get, pass 0. The server.listen documentation says that with a port of 0 the OS assigns an arbitrary unused port, and you read it back from server.address().port after the 'listening' event. That's ideal for integration tests, which otherwise fight each other over a hard-coded port.

Once your API moves to a new port, the browser treats it as a different origin. If requests from your front end suddenly fail, read which header is missing when you hit a CORS error before assuming the port change broke something else.

Handle EADDRINUSE inside your Node app#

A listen failure is an 'error' event on the server. Subscribe to it and the crash turns into a message you control. This example takes a port, deliberately collides with it, and prints the fields you'd want in a log line:

const net = require('node:net');

const first = net.createServer();

first.listen(0, '127.0.0.1', () => {
  const { port } = first.address();
  console.log(`first server is listening on 127.0.0.1:${port}`);

  const second = net.createServer();

  second.on('error', (err) => {
    console.log('second server failed to listen');
    console.log('  code:    ' + err.code);
    console.log('  syscall: ' + err.syscall);
    console.log('  address: ' + err.address);
    console.log('  port:    ' + err.port);
    console.log('  message: ' + err.message);
    first.close(() => console.log('first server closed, port released'));
  });

  second.listen(port, '127.0.0.1');
});

The pattern Node's own docs suggest for transient conflicts is to retry after a delay:

server.on('error', (e) => {
  if (e.code === 'EADDRINUSE') {
    console.error('Address in use, retrying...');
    setTimeout(() => {
      server.close();
      server.listen(PORT, HOST);
    }, 1000);
  }
});

That helps when a previous instance is still shutting down, as in a rolling restart. It won't help against a process that's going to keep the port forever, so cap the retries or combine them with a fallback. Here's a version that tries the preferred port and falls back to an OS-assigned one:

const net = require('node:net');

// Occupy a random free port so the demo collides on purpose.
const blocker = net.createServer();

blocker.listen(0, '127.0.0.1', () => {
  const wanted = blocker.address().port;
  const app = net.createServer();

  app.once('error', (err) => {
    if (err.code !== 'EADDRINUSE') throw err;
    console.log(`port ${wanted} is busy, asking the OS for a free one`);
    app.listen(0, '127.0.0.1');
  });

  app.on('listening', () => {
    console.log(`app is listening on ${app.address().port}`);
    app.close();
    blocker.close();
  });

  app.listen(wanted, '127.0.0.1');
});

Two rules from the docs matter here. server.listen() may be called again only after an error or after server.close(). Calling it on a server that's already listening throws ERR_SERVER_ALREADY_LISTEN, which is a bug in your code rather than a port conflict. And server.close() is asynchronous. It stops accepting new connections and emits 'close' once existing ones end, so the port isn't necessarily free the instant you call it.

Which process usually owns ports 3000, 5000, 8080 and 443#

The port number in the error is a strong hint about the culprit.

On Linux, ports below 1024 need elevated privileges, so an unprivileged bind to 443 fails with EACCES rather than EADDRINUSE. If you do see EADDRINUSE on 443, you were already running with enough rights and something real is serving HTTPS there.

Common mistakes and gotchas#

• Killing the child of a watcher. Tools like nodemon restart the child process when it dies, so killing the node PID just makes the watcher spawn a fresh one that grabs the port again. Find the terminal running the watcher and stop it there with Ctrl+C, or kill the parent PID.
• Killing a Docker proxy instead of the container. When a container publishes a port, lsof shows a Docker helper process as the owner. Killing it leaves the container running and Docker will often put the proxy back. Use docker ps and docker stop on the container. If Docker commands themselves fail for you, the Docker socket permission fix is usually the reason.
• Looking on the wrong side of WSL. On Windows with WSL 2, a server started inside the Linux VM is forwarded to Windows, and vice versa can appear busy from inside. Run ss inside WSL and netstat -ano in Windows before concluding the port is free.
• Mixing up IPv4 and IPv6. Node binds :: by default, which on most systems also claims 0.0.0.0. A process bound to 127.0.0.1:3000 or 0.0.0.0:3000 can therefore block you even though your error says :::3000. lsof -iTCP:3000 shows both families, so trust it over a search for the literal ::.
• Calling listen twice. ERR_SERVER_ALREADY_LISTEN looks related but isn't. It means your code called server.listen() on a server that's already up, often from a module that gets imported twice.
• Reaching for reusePort. The reusePort option on server.listen() lets multiple sockets deliberately share a port with the OS distributing connections between them. It's supported only on some platforms (Linux 3.9+, FreeBSD 12.0+ and a few others) and raises an error elsewhere. It's a load-sharing feature, not a way to paper over a stray process.
• Cluster workers fighting over a handle. In cluster mode, workers share the listening handle by default. Setting exclusive: true stops that sharing, and a second worker then fails with a port error. Leave it at the default unless you specifically want separate handles.
• Expecting close() to free the port instantly. server.close() waits for existing connections to end. A restart script that calls it and immediately starts a new listener can hit EADDRINUSE from its own previous instance. Wait for the 'close' event.

Quick reference#

Work down this list and stop at the first step that fixes it.

1. Read port and address from the error object, not the stack trace.
2. Find the owner. macOS and Linux: lsof -nP -iTCP:3000 -sTCP:LISTEN. Linux: ss -ltnp | grep ':3000'. Windows: netstat -ano | findstr :3000.
3. Identify it before killing: ps -p PID -o args= or tasklist /FI "PID eq PID".
4. Stop it gently: kill PID or taskkill /PID PID /F. Then re-run step 2 to confirm.
5. Only if it survives: kill -9 PID, after confirming it's a stray dev process and not a database or system service.
6. If you can't or shouldn't kill it, run on another port: PORT=3001 node server.js, or pass 0 and read server.address().port.
7. Add an 'error' listener on the server so the next conflict logs a message instead of crashing.
8. Watchers, Docker containers and WSL are the usual reasons the port looks free but isn't.

Quick answers