AI Diagnostic Summary

Error: listen EADDRINUSE

Well-Documented Error

This error matches known, documented patterns with reliable solutions.

Quick Fix (Most Common Solution)

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.

High confidence
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.

Based on documented solutions and common real-world fixes.
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
  1. Kill the process using the port
  2. Use a different port number
  3. 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

  1. lsof -i :3000
  2. kill -9
  3. Or use: npx kill-port 3000

Windows (PowerShell)

  1. netstat -ano | findstr :3000
  2. taskkill /F /PID
  3. Or 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

EADDRINUSE in CI environments almost always stems from parallel test execution. Jest, Mocha, and Vitest with --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?

Explanations are based on documented fixes, real-world reports, and common system behavior. GetErrorHelp is independent and not affiliated with software vendors, device manufacturers, or service providers.
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

Common Search Variations

Related Errors
Still Stuck?

Paste a different error message or upload a screenshot to get help instantly.

Solutions are based on commonly documented fixes and may not apply in all situations.