Fix “EADDRINUSE: address already in use” on a local port

By

Updated

Reproduce the error with a throwaway server, see which process and project hold the port, and stop the right process tree with Port Pilot's ports kill.

Your server dies before it starts:

Error: listen EADDRINUSE: address already in use 127.0.0.1:43127

Another process is already listening on that address and port, and the operating system won’t give it to a second one. You have two ways out: stop the other process, or start yours on another port. The hard part is knowing which one is safe, because lsof only tells you the other process is node.

We’ll reproduce the error with a throwaway server, then use Port Pilot’s ports command to see what holds the port and stop it. The plain lsof and kill version is in find and kill the process using a port.

What the error looks like

Every runtime says it differently. These are the messages I got on macOS when port 43127 was taken:

What you runWhat it prints
Node.js 22Error: listen EADDRINUSE: address already in use 127.0.0.1:43127
python3 -m http.server 43127OSError: [Errno 48] Address already in use
Vite 7Port 43127 is in use, trying another one... then starts on 43128
Vite 7 with --strictPortError: Port 43127 is already in use

Node prints the address it tried. :::3000 means it tried every address, 127.0.0.1:43127 that it tried localhost only. Python doesn’t print the port, so take it from your command.

Vite doesn’t fail at all. It moves to the next free port, which is how you end up with two copies of the same app on 5173 and 5174 and a browser tab still on the old one. Astro behaves the same way.

Reproduce it with a throwaway server

Make a folder called port-practice with a package.json in it, so Port Pilot has a project name to show. I made mine in a temporary folder:

{
  "name": "port-practice",
  "private": true,
  "scripts": {
    "start": "node server.mjs"
  }
}

Then server.mjs, a server that answers with a page title we can recognize:

import { createServer } from 'node:http'

createServer((request, response) => {
  response.writeHead(200, { 'Content-Type': 'text/html' })
  response.end('<title>Port practice</title><h1>Practice server</h1>')
}).listen(43127, '127.0.0.1', () => {
  console.log(`Practice server PID ${process.pid} on port 43127`)
})

Start it with npm start and leave that terminal open. In a second terminal, run the same file again:

node server.mjs
Error: listen EADDRINUSE: address already in use 127.0.0.1:43127
    at Server.setupListenHandle [as _listen2] (node:net:1941:16)
    ...
  code: 'EADDRINUSE',
  errno: -48,
  syscall: 'listen',
  address: '127.0.0.1',
  port: 43127
}

The first server is still running. That’s the situation you’re in with a real dev server.

See what holds the port

ports check 43127
● Port 43127 is in use

  PID:       55399
  User:      flaviocopes
  Command:   node server.mjs
  Project:   port-practice
  Framework: Node.js
  Directory: /private/tmp/claude-501/port-practice
  Chain:     npm start  → node server.mjs
  CPU:       0.0%
  Memory:    42 MB
  Uptime:    7s
  HTTP:      200 http://localhost:43127/ (30ms)
  Title:     Port practice

  Stop it with: ports kill 43127

The project comes from the name in package.json, the directory from the process’s working directory, and the title from the page. The chain shows npm start launched it.

If you’d rather click, the Port Pilot menu bar app lists the same listeners:

The Port Pilot menu bar panel listing four listening ports, with port-practice on 43127 at the bottom, running node, HTTP 200

Click the row for 43127 to open its details, with the same PID, command, directory and chain:

The Port Pilot details for port-practice on port 43127, with HTTP 200, the PID, user admin, the page title Port practice, the command node server.mjs, the directory /Users/admin/Projects/port-practice, the process chain npm start to node server.mjs, and a Stop Service button

With a real dev server, this is where you decide. Find what’s using a port on macOS goes through each field and what to do when the port doesn’t appear in ports list.

Decide what to do when a port is already in useCheck what holds the port. If you still need that process, start your server on another port. If it runs in a terminal you can see, press Ctrl+C there. If it is a Docker container, stop the container. Otherwise stop it with ports kill, check the port is free, and start your server again.YesNoYesNoYesNoServer fails withEADDRINUSEports check the portStill need thatprocess?Start yours onanother portRunning in aterminal you cansee?Press Ctrl+C thereDocker container?docker stop thecontainerports kill the portports is-free theportStart your serveragain

If it’s a project you still want running, leave it and change your port. Most dev servers take --port or a PORT variable, and I wrote how to change a Next.js app port. If it’s in another terminal tab, press Ctrl+C there, so its own shutdown code runs. A container goes down with docker stop and its name, once you know which container published the port.

ports kill is for the rest: the server you started in the background and forgot, or the one that outlived the terminal that started it.

Stop it

ports kill 43127
  Port:      43127
  PID:       55399
  Project:   port-practice
  Directory: /private/tmp/claude-501/port-practice
  Command:   node server.mjs
  Chain:     npm start  → node server.mjs

Stop this process tree with SIGTERM? [y/N]

Nothing has stopped yet. Anything other than y or yes cancels. In the menu bar app, Stop Service… at the bottom of the details asks first too, with “Stop the process tree on port 43127?”, then runs ports kill for you. When you confirm:

✓ Freed port 43127; signaled 1 process

npm start exits on its own once its child is gone. Check the port before you start your server again:

ports is-free 43127
Port 43127 is free

is-free exits with 0 when the port is free and 1 when it’s taken, so ports is-free 3000 && npm run dev only starts the server on a free port.

What kill does to a process tree

Dev servers rarely run as one process. Port Pilot collects every descendant of the listening process from the ps table and signals them first, the deepest ones before their parents, then the listener itself. It sends SIGTERM, waits 1.2 seconds, and sends SIGKILL to any process still running.

To see that, here’s a server that ignores SIGTERM and starts a child process:

import { createServer } from 'node:http'
import { spawn } from 'node:child_process'

spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { stdio: 'ignore' })
process.on('SIGTERM', () => console.log('Ignoring SIGTERM'))

createServer((request, response) => {
  response.end('stubborn')
}).listen(43128, '127.0.0.1')
ports kill 43128 --yes
✓ Freed port 43128; signaled 2 processes
  Forced 1 process after timeout

The child stopped on SIGTERM. The server printed “Ignoring SIGTERM” and got SIGKILL 1.2 seconds later, so the whole command took under 2 seconds.

--signal INT starts with SIGINT instead, which is what Ctrl+C sends. --signal KILL skips the grace period.

Signals only reach processes below the listener. If the chain shows a process manager or a file watcher above it, that parent can start the server again a second later. Stop the parent where it runs.

Scripts and agents

ports kill only asks when it runs in a terminal. Without one, it prints the preview and gives up:

  Port:      43127
  PID:       55399
  ...
Cancelled.

It exits with 0 even then, so a script can’t tell from the exit code that nothing was stopped. Run ports is-free afterwards.

--json doesn’t count as a yes either:

ports kill 43127 --json
Error: --json requires --yes for destructive actions

Only pass --yes for processes the script or the agent started itself. For everything else, have the agent look and ask. This goes in a project’s agent instructions:

Before starting the dev server, run `ports is-free 3000`. If the port is
taken, run `ports check 3000 --json` and tell me what is listening there.
Don't stop a process you didn't start without asking me first.

In the dashboard

In the ports dashboard, select the row and press K (capital K, labeled “Stop safely” in the key bar). The confirmation is shorter than the CLI’s: “Stop”, the project name and the port, then [y/N]. Read the chain on the line under the table before you press y.

The Port Pilot terminal dashboard listing six development services with port, project, framework, PID, memory, uptime, HTTP status and command, port 8080 selected with a 503, the chain npm run dev to server.js under the table, and a key bar that starts with K Stop safely

When it’s still busy

If port 5000 or 7000 is taken by ControlCenter, that’s AirPlay Receiver. Turn it off in System Settings or use another port.

If ports check says the port is free and your server still fails, the listener may belong to another user. lsof only sees other users’ processes with sudo lsof -i :3000.

If ports: command not found, run npm link again in the Port Pilot folder and open a new terminal.

Get Port Pilot

Inspect local services, check their health, and stop the right process through a terminal dashboard, CLI, or macOS menu bar app.

See Port Pilot → · Read the docs · $20. See the app page for tax details, with full source code.

More tutorials for my apps →

Want me to talk about your product? You can sponsor this site.