Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js cannot start because the port is already taken

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

Short answer

EADDRINUSE means another socket already listens on that port, so Node's listen() was refused. Find the owner of the port with ss or lsof. It is usually an old copy of your app, a PM2 entry that still runs, a second server in the same code, or a container that publishes the port.

  • Applies to Node.js 22 and 24, PM2, Docker Engine 28, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the system who owns the port. The output names the process id and the program; everything below depends on what that program is.

    sudo ss -ltnp 'sport = :3000'
    # or
    sudo lsof -nP -iTCP:3000 -sTCP:LISTEN
  2. 2Match what you see, then jump to its fix

    1. 1The process on the port is node (or npm) started from your project, often in a terminal you forgot or a crashed watcherAn older copy of your own app is still runningFix
    2. 2The process on the port is a PM2 child (parent is PM2), or pm2 list shows the app onlinePM2 already runs the app, and you started another by handFix
    3. 3The app fails on its own at start, with nothing else on the port before you launch itTwo servers inside the same app listen on one portFix
    4. 4docker ps shows a container whose PORTS column maps the same host portA Docker container publishes the port on the hostFix

What does the error look like?

  • Error: listen EADDRINUSE: address already in use :::3000
  • Error: listen EADDRINUSE: address already in use 127.0.0.1:8080
  • code: 'EADDRINUSE', syscall: 'listen', port: 3000

Cause 1 of 4

An older copy of your own app is still running

1Check

Look at the full command line and working directory of the process that holds the port, to be sure it is yours and not a service you need.

sudo lsof -t -nP -iTCP:3000 -sTCP:LISTEN
ps -o pid,etime,args -p <pid>

2Fix

Stop it with a normal termination signal first. Use kill -9 only if it does not exit.

kill <pid>

3Verify

The port is free, then the app starts.

sudo ss -ltnp 'sport = :3000'
npm start

Confirmed by man7.org

Did this fix it?

Cause 2 of 4

PM2 already runs the app, and you started another by hand

1Check

PM2 keeps apps alive and restarts them if they die, so killing the process id only brings it back. List what PM2 manages.

pm2 list

2Fix

Stop or remove the entry through PM2 instead of killing the process. Remove duplicate entries of the same app so only one is left.

pm2 stop my-app
# remove it from the list completely
pm2 delete my-app

3Verify

PM2 no longer lists the entry and the port is free.

pm2 list
sudo ss -ltnp 'sport = :3000'

Confirmed by pm2.keymetrics.io

Did this fix it?

Cause 3 of 4

Two servers inside the same app listen on one port

1Check

Every call to listen() on a server needs its own free port. A second HTTP server or a leftover test file can ask for the port the first one already holds. Search the code for every listen call.

grep -rn --include='*.js' --include='*.ts' --exclude-dir=node_modules 'listen(' .

2Fix

Give each server its own port, read from configuration so nothing is hard-coded twice.

http.createServer(app).listen(process.env.PORT || 3000);
http.createServer(adminApp).listen(process.env.ADMIN_PORT || 3001);

3Verify

The app starts and only one process is listening.

sudo ss -ltnp 'sport = :3000'

Confirmed by nodejs.org

Did this fix it?

Cause 4 of 4

A Docker container publishes the port on the host

1Check

A published port (-p host:container) occupies the host side for as long as the container runs. See which container publishes the port.

docker ps --filter publish=3000

2Fix

Stop that container, or publish yours on a different host port; the number after the colon is the port inside the container and stays the same.

docker stop <container>
# or keep both, with a new host port
docker run -p 3001:3000 my-app

3Verify

Both start; the new host port answers.

curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Read the port from process.env.PORT so a second instance can be started on another port.
  • Run long-lived apps under one manager (PM2 or systemd) and stop them through it, not with kill.
  • Bind development servers to 127.0.0.1 and publish container ports with an explicit host side, so conflicts are visible in one place.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.