Error: listen EADDRINUSE: address already in use — how to fix it
Your server tried to listen on a port that another process on the same machine already holds. On your computer, stop the old process, usually a dev server still running in another terminal. In a deploy, it almost always means the app starts its server twice, or two processes in one container ask for the same port.
By Livops team, the people who build and run LivopsUpdated
What Node prints when it happens:
Error: listen EADDRINUSE: address already in use :::3000
at Server.setupListenHandle [as _listen2] (node:net)
...
code: 'EADDRINUSE',
errno: -98,
syscall: 'listen',
address: '::',
port: 3000
}
Python’s version is OSError: [Errno 98] Address already in use. This page explains the error, lists the causes from the most common, shows how to confirm only one process owns the port, and says how this looks on Livops.
What does the error mean?
EADDRINUSE means an attempt to bind a server to a local address failed because another server on the same system already occupies that address[1]. A port can have one listener at a time. Node’s own documentation calls it one of the most common errors raised when listening[2].
The process that holds the port may be another program, a second copy of your app, or your app itself, if it calls listen twice.
Causes, most common first
1. An old copy is still running (on your computer)
A dev server in another terminal, a process left behind when an editor crashed, a container you started yesterday. Find it and stop it:
lsof -i :3000 # macOS and Linux: shows the PID
kill <pid>
ss -ltnp | grep :3000 # Linux
docker ps # a container publishing 3000
On Windows, netstat -ano | findstr :3000, then taskkill /PID <pid> /F.
2. The code starts the server twice
app.listen() in app.js, and again in server.js or bin/www, which imports app.js. Each listen creates its own server, and the second one finds the port taken. Keep one: export the app from one file and listen only in the entry point.
// app.js
export const app = express()
// server.js
import { app } from './app.js'
app.listen(process.env.PORT || 3000, '0.0.0.0')
3. Two processes in one container ask for one port
A start script like npm run api & npm run web where both read PORT, or concurrently running a server and a preview. Give each process its own port, or run them as two services. (Node’s cluster module is different: its workers share one port through the primary process on purpose.)
4. A file watcher restarts faster than the old process exits
nodemon, ts-node-dev or node --watch start the new process while the old one is still closing. This is a development problem; in production start the built app directly, for example node dist/server.js, never a watcher.
5. Tests run in parallel on a fixed port
Each test file starts the server on 3000. Listen on port 0 in tests: the operating system then assigns an unused port, which server.address().port tells you[2].
If you want the app to wait and retry instead of crashing, Node’s documentation shows handling the error event with e.code === 'EADDRINUSE'[2]. That only hides cause 2 or 3; fix those first.
How to confirm the fix locally
-
Before starting, check nothing listens on the port:
lsof -i :3000prints nothing. -
Start the app once, the way the server starts it:
PORT=3000 npm start. -
Check it answers and that exactly one process holds the port:
curl -i http://127.0.0.1:3000/ lsof -nP -iTCP:3000 -sTCP:LISTEN
One line in the lsof output means one listener. Two PIDs there, or the error on start, means cause 2 or 3 is still in the code.
On Livops
- Every version gets its own container. Each deploy starts the new version in a separate container with its own network, while the old one keeps serving until the new one answers. The old version holding the port is therefore never the cause. If you see
EADDRINUSEon Livops, two things inside your new container asked for the same port: cause 2 or 3. - The port is given to you. The app is told where to listen in the
PORTvariable (3000 by default; for a Docker image, the port you specified). Listen onPORT, on0.0.0.0. - A crash on start is a failed deploy, not an outage. If the app exits on this error, the deploy fails as
start_failed, the log shows the app’s last lines with the error, and the previous version keeps running. - No dedicated Tip for this error. Livops has no Tip line written for
EADDRINUSE. The assistant’s button next to the failed deploy reads the log and explains it; it does not change your code or the start command unless you press a card it proposes.
More on failed starts: The app did not start.
Questions
How do I find which process uses the port?
On macOS and Linux, lsof -i :3000 shows the process and its PID; on Linux, ss -ltnp | grep 3000 does too. On Windows, netstat -ano | findstr :3000 gives the PID, and taskkill /PID <pid> /F stops it.
Is it the same error in Python?
Yes. Python says OSError: [Errno 98] Address already in use on Linux, and Errno 48 on macOS. The causes and fixes are the same.
Should I just pick another port?
Locally that works. On a platform, no: listen on the port in the PORT variable and remove whatever else is listening on it. Picking a different number moves the app away from the address the platform sends traffic to.
Why do my tests fail with EADDRINUSE?
Test files run in parallel and each starts the server on the same port. Listen on port 0 in tests, and the operating system picks a free port for each.
Can the previous version of my app cause it on Livops?
No. Each version runs in its own container with its own network, so the old version keeps its port to itself. If the error appears, two things inside your new container asked for the same port.
Sources
- Node.js docs — Errors, common system errors (nodejs.org). Checked .
- Node.js docs — net, server.listen() (nodejs.org). Checked .
Put your project online today
Connect GitHub or drop a folder. No card is asked for.
Deploy your appRelated
- App not listening on $PORT: why the health check failed after deployThe platform started your app, tried the port it gave it, and nothing answered in time. Almost always the app listens on its own fixed port instead of the PORT variable, listens on localhost (127.0.0.1) instead of 0.0.0.0, or crashed or was still starting when the check gave up. Listen on 0.0.0.0 and the port in PORT, and it passes.
- npm ERR! code 1: why the build failed with exit code 1npm ERR! code 1 (npm error code 1 in newer npm) only says that a script npm ran exited with code 1. The real error is printed above it: usually a compile or type error, a lockfile out of sync with package.json, or a dependency whose install script failed. Find the first error line above code 1, fix that, and the build passes.
- Gunicorn "Worker failed to boot": what it means and how to fix itGunicorn's worker could not load your application, so the master process shut down. The cause is the Python traceback printed just above the message: most often a missing package or variable, or a wrong module:variable path in the gunicorn command. Fix what the traceback names and the workers boot.