Node.js cannot start because the port is already taken
Error: listen EADDRINUSE: address already in use :::3000Short 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.
Fix it fast
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:LISTEN2Match what you see, then jump to its fix
- 1
The 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
The 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
The 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
docker ps shows a container whose PORTS column maps the same host portA Docker container publishes the port on the hostFix
- 1
What does the error look like?
Error: listen EADDRINUSE: address already in use :::3000Error: listen EADDRINUSE: address already in use 127.0.0.1:8080code: '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 startConfirmed by man7.org
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 list2Fix
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-app3Verify
PM2 no longer lists the entry and the port is free.
pm2 list
sudo ss -ltnp 'sport = :3000'Confirmed by pm2.keymetrics.io
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
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=30002Fix
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-app3Verify
Both start; the new host port answers.
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3001Confirmed by docs.docker.com
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
Related fixes
Back end
Node.js request fails with getaddrinfo EAI_AGAIN
errno: -3001, code: 'EAI_AGAIN', syscall: 'getaddrinfo'
EAI_AGAIN means the system resolver asked a name server and got a temporary failure back.
3 causes, each with a fixBack end
Node.js https request fails with getaddrinfo ENOTFOUND
getaddrinfo ENOTFOUND
ENOTFOUND means the name lookup failed before any connection was made.
3 causes, each with a fixBack end
process.env.NODE_ENV is undefined in a Node.js app
console.log(process.env.NODE_ENV) prints undefined
Node.js does not set NODE_ENV for you.
5 causes, each with a fixBack end
PM2 does not restart my Node.js app after it crashes
status stopped in pm2 list
PM2 restarts a crashed process on its own, so a process that stays down has a reason.
3 causes, each with a fixBack end
PM2 says the ecosystem file is malformated and refuses to start
Error [ERR_REQUIRE_ASYNC_MODULE]
PM2 prints 'malformated' whenever loading the config file throws.
3 causes, each with a fixBack end
Loading a .env file into a PM2 ecosystem config fails or gives undefined values
[PM2][ERROR] File ecosystem.config.js malformated
PM2 only passes the env block of the config to your app.
4 causes, each with a fix