Error: listen EADDRINUSE
This error matches known, documented patterns with reliable solutions.
Quick Fix (Most Common Solution)
- Kill the process using the port
- Use a different port number
Seeing "Error: listen EADDRINUSE"? This error can be frustrating, but it's usually fixable. It typically affects your development workflow or system. Below you'll find clear, step-by-step solutions to resolve this issue.
What This Error Means
Another application is already listening on the port you are trying to use.
Frequently documented in developer and vendor support forums.
Not affiliated with browser, OS, or device manufacturers.
New here? Learn why exact error messages matter →
Common Causes
- Previous server still running
- Another app using same port
- Zombie Node process
How to Fix
- Kill the process using the port
- Use a different port number
- Find process with lsof -i :PORT
Last reviewed: April 2026 How we review solutions
Version note: Affects all Node.js versions. More frequent in development with hot-reload tools (nodemon, ts-node-dev) that may not clean up child processes on crash.
Environment-Specific Commands
Linux / macOS
lsof -i :3000kill -9Or use: npx kill-port 3000
Windows (PowerShell)
netstat -ano | findstr :3000taskkill /F /PIDOr use: npx kill-port 3000
Quick Diagnostic Path
- If lsof shows no process on the port → The port may be in TIME_WAIT. Wait 60 seconds or restart with a different port.
- If The PID belongs to a system process (PID < 1000) → Choose a different port. System services on low ports require root to override.
- If Happens every time you restart your dev server → Add a graceful shutdown handler: process.on("SIGTERM", () => server.close())
If This Still Fails, Check
- Port held by a process in TIME_WAIT state: wait 30–60 seconds or use SO_REUSEADDR in your server options
- WSL2 port conflict with Windows host: check both WSL and Windows processes on the same port
- Docker port mapping collision: docker ps may reveal a container already bound to the port
Graceful shutdown to prevent port leaks (Node.js)
const server = app.listen(3000, () => {
console.log("Server running on port 3000");
});
process.on("SIGTERM", () => server.close());
process.on("SIGINT", () => server.close());CI/CD Considerations
Parallel Test Runners and Port Collisions in CI
--concurrent or --workers flags can start multiple test suites simultaneously, each trying to launch a server on the same port. The default port 3000 or 8080 hardcoded in test setup files becomes a conflict when two worker processes reach the server-start line simultaneously.
The fix: use dynamic port assignment in tests. server.listen(0) assigns the next available port, which the test can retrieve with server.address().port. A test helper wrapper that manages port assignment prevents all inter-worker conflicts.
GitHub Actions runners share the network namespace across jobs in the same workflow. If two parallel jobs both start servers on port 8080 — even when the jobs seem independent — EADDRINUSE appears. Using matrix strategies with different port offsets, or passing --port=0 to your dev server command, solves this. Self-hosted runners that reuse the same host machine across pipeline runs carry an additional risk: a crashed previous run may have left a process holding the port. A pre-test step running npx kill-port 3000 8080 (or the platform equivalent) on the runner prevents carry-over conflicts between pipeline runs.Need reliable hosting?
DigitalOcean offers simple cloud infrastructure with $200 free credit for new users.
Try DigitalOcean →We may earn a commission from tools recommended in our fixes.
Optional follow-up
Some users ask whether saving fixes for recurring errors would be useful when the same issue appears again.
Was this explanation helpful?
Frequently Asked Questions
How do I find what uses a port?
On Unix: lsof -i :3000. On Windows: netstat -ano | findstr :3000
How do I kill a port process?
Find PID with above commands, then kill PID or taskkill /F /PID PID
Related Resources
Also Known As
- Node.js error
- Node runtime error
- JavaScript server error
- Node exception
Common Search Variations
- "node js error fix"
- "node command not working"
- "node app crashing"
- "javascript server error solution"
- "node runtime crash fix"
- "how to debug node error"
Related Errors
Still Stuck?
Paste a different error message or upload a screenshot to get help instantly.