Skip to content

Freeing a port stuck with EADDRINUSE

Identifies what actually holds the port, checks whether it's an orphaned instance of the same app versus a different legitimate service, and verifies the port is free afterward. It does not cover a port genuinely reserved by the OS or blocked by a firewall — EADDRINUSE specifically means something is bound, not that access is denied.

Node.js
Unverifiedno reproductions yetWhy this confidence?
Revision 1published by DevYou curationrevision history
Run the diagnosisEvidence and compatibility

Symptoms

The diagnostic path

8 steps. Every step is written out below in full — the interactive version simply follows the branches for you.

  1. Step 1 · StartNode process crashes on startup with EADDRINUSE

    Something else already has this exact port bound. The fix depends on whether that's a leftover instance of your own app or a different service that legitimately needs the port.

    What happens next

    • passed → step 2, Find out what's already using the port

  2. Step 2 · TestFind out what's already using the port

    On Linux/macOS use lsof or ss; on Windows use netstat with findstr, then look up the owning process by PID.

    Read-onlypowershell
    netstat -ano | findstr :8787

    Expected result

      TCP    0.0.0.0:8787           0.0.0.0:0              LISTENING       14832

    What happens next

    • passed → step 3, Is the process holding the port an old instance of this same app?
    • failed → step 4, Nothing is bound to that port right now
    • unknown → step 3, Is the process holding the port an old instance of this same app?

  3. Step 3 · TestIs the process holding the port an old instance of this same app?

    Check the owning PID's command line against this project — a very common dev-mode cause is a previous run (via nodemon or npm run dev) that didn't fully exit.

    Read-onlypowershell
    Get-CimInstance Win32_Process -Filter "ProcessId = 14832" | Select-Object CommandLine

    Expected result

    CommandLine
-----------
node C:\projects\api\src\server.js

    What happens next

    • passed → step 5, Fix: terminate the leftover process
    • failed → step 6, Root cause: a different, legitimate service owns that port
    • unknown → step 6, Root cause: a different, legitimate service owns that port

  4. Step 4 · EndNothing is bound to that port right now

    The port isn't actually in use any more — it may have already been released, or on Windows in particular can briefly show as in-use during TIME_WAIT for a few seconds after a process exits. Re-run and see if it recurs.

  5. Step 5 · FixFix: terminate the leftover process

    Confirm the PID and command line first — force-killing the wrong process can lose unsaved work in whatever it actually is.

    Changes statepowershell

    Changes system or service state. Review before running.

    Force-terminates that process immediately, releasing any port or resource it held.

    taskkill /PID 14832 /F

    What happens next

    • passed → step 7, Confirm the port is free and the app starts

  6. Step 6 · Root causeRoot cause: a different, legitimate service owns that port

    The process holding the port isn't this app — either stop that other service if you don't actually need both running, or change this app's own port (its PORT env var or config) instead of freeing a port something else needs.

  7. Step 7 · Verify the fixConfirm the port is free and the app starts

    Re-check the port, then start the app again.

    Read-onlypowershell
    netstat -ano | findstr :8787

    Expected result

    (no output)

    What happens next

    • passed → step 8, Resolved
    • failed → step 2, Find out what's already using the port
    • unknown → step 2, Find out what's already using the port

  8. Step 8 · EndResolved

    The port is free and the app starts normally.

Sources

Why this confidence?

What would strengthen it: 6 more independent reproductions. Reproductions from 3 more distinct environments.