Node.js Error EADDRINUSE: Address already in use

Identify: does your log match?

node:events:497
      throw er; // Unhandled 'error' event
      ^

Error: listen EADDRINUSE: address already in use :::3000
    at Server.setupListenHandle [as _listen2] (node:net:1904:16)
    at listenInCluster (node:net:1952:12)
    at Server.listen (node:net:2063:7) {
  code: 'EADDRINUSE',
  errno: -98,
  syscall: 'listen',
  address: '::',
  port: 3000
}

1. High

   Orphaned previous dev server

   A crashed terminal, nodemon restart or IDE run left the old process alive and holding the port.

2. Medium

   listen() called twice

   Importing the app module twice, or calling app.listen in both server.ts and a test, binds the same port twice in one process.

3. Medium

   Another service owns the port

   macOS AirPlay Receiver uses 5000 and 7000; Docker containers publish ports on the host.

Fix

npm run dev   # EADDRINUSE again

lsof -nP -iTCP:3000 -sTCP:LISTEN
kill $(lsof -ti tcp:3000)        # SIGTERM; use kill -9 only if it ignores it
# Windows: netstat -ano | findstr :3000  then  taskkill /PID <pid> /F

Verify: reproduce it on purpose

$ node -e "const n=require('net');n.createServer().listen(3000,()=>n.createServer().listen(3000).on('error',e=>{console.log(e.code);process.exit()}))"

Prevent

• Read PORT from env.
• Use supertest(app) instead of listening in tests.
• Handle SIGTERM in every long-running process.