Fix "listen EADDRINUSE: address already in use :::3000" in VS Code Debug

TL;DR

Another process is already listening on port 3000. Kill it, then restart your debug session.

# macOS / Linux
lsof -ti :3000 | xargs kill -9

# Windows (PowerShell)
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process -Force

A previous debug session that didn't exit cleanly is usually the culprit — read on for the full picture.

What's happening

Every time you hit F5, VS Code spins up a Node.js process (or dev server) and binds it to a port — port 3000 here. That part is normal. The problem starts when a previous session crashes, gets force-killed, or VS Code just loses track of it.

That old process keeps running in the background, silently holding the port. The next debug session tries to claim the same port and immediately fails:

listen EADDRINUSE: address already in use :::3000

The ::: prefix means the process bound to all IPv6 interfaces — which on most systems includes IPv4 too. So switching between localhost and 127.0.0.1 won't help. You need to kill the process outright.

Fix 1: Kill the process on the port

macOS / Linux

# Find and kill in one line
lsof -ti :3000 | xargs kill -9

# Or step by step:
lsof -i :3000
# Note the PID in the output, then:
kill -9 <PID>

Windows (Command Prompt)

netstat -ano | findstr :3000
# Note the PID in the last column, then:
taskkill /PID <PID> /F

Windows (PowerShell)

Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process -Force

After killing the process, press F5 again. The error should be gone.

Fix 2: Stop orphaned VS Code debug sessions

Sometimes the ghost process belongs to a previous VS Code debug session. You can kill it without leaving the editor:

• Open the Run and Debug panel (Ctrl+Shift+D / Cmd+Shift+D)
• Click the red square Stop button if any session shows as active
• Switch to the Terminal panel and Ctrl+C any processes still running there

This one trips people up: VS Code's integrated terminals keep processes alive even after the debug session appears to have ended in the UI. Check every terminal tab — you might have three or four open from earlier runs.

Fix 3: Change the debug port

Port 3000 legitimately occupied? Maybe another project is running there, or a system service grabbed it on startup. Rather than killing it, just move your app to a different port.

In your .env file:

PORT=3001

Or pass it inline when starting:

PORT=3001 node server.js

For Vite projects, update vite.config.ts:

export default defineConfig({
  server: {
    port: 3001
  }
})

For Create React App, set PORT=3001 in your .env file — CRA picks it up automatically.

Fix 4: Configure VS Code to auto-kill on restart

Add "restart": true to your .vscode/launch.json. This tells VS Code to restart the debug session automatically whenever the process exits — so stale processes get cleaned up between runs:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch Program",
      "program": "${workspaceFolder}/index.js",
      "restart": true,
      "autoAttachChildProcesses": true
    }
  ]
}

For servers that need an explicit kill step before relaunch, add a preLaunchTask that runs your kill command. Some debug adapters also support "killOnServerStop" — check your adapter's docs.

Fix 5: Use the kill-port package

If you hit EADDRINUSE every other day, stop dealing with it manually. Add kill-port as a dev dependency:

npm install --save-dev kill-port

Then wire it into package.json as a predev hook:

"scripts": {
  "predev": "kill-port 3000",
  "dev": "node server.js"
}

Every npm run dev now clears the port before your server starts. Zero extra commands.

Verify the fix

Before hitting F5, confirm the port is actually free:

# macOS / Linux
lsof -i :3000
# Should return nothing

# Windows
netstat -ano | findstr :3000
# Should return nothing

No output means the port is clear. Your next debug session should start cleanly.

Why this keeps happening

Four situations trigger this repeatedly:

• Clicking Restart in VS Code before the previous process has fully exited
• VS Code crashing or being force-quit mid-session
• Running npm run dev in a terminal tab and launching the debugger with F5 simultaneously
• Docker containers or other services mapped to the same host port

The best long-term habit: glance at the Terminal panel before every F5. Kill anything still running there. It takes two seconds and prevents 90% of these errors.

For a fully automated solution, the predev script from Fix 5 handles it without any manual intervention.