mcpField
D
detecting-port-conflicts

detecting-port-conflicts

github.com/spencerpaulyDevelopment868424 installsUpdated 13w ago
Repository

About detecting-port-conflicts

A development skill for diagnosing port-in-use errors and choosing a way to resume a server. It guides process inspection, termination, or switching to another port.

Key features

  1. 01Recognizes common port-conflict errors
  2. 02Finds processes using a port with lsof
  3. 03Offers process termination or port changes
  4. 04Warns before terminating all Node processes

Use cases

  1. 01Investigating why a development server will not start
  2. 02Identifying a process that is blocking a port
  3. 03Restarting a server on an available port

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/spencerpauly/awesome-cursor-skills --skill detecting-port-conflicts

After installing, type/detecting-port-conflictsin Claude Code to confirm it loaded.

Details

From the project README

Detecting Port Conflicts

When a dev server fails to start because a port is already in use, diagnose and resolve it.

Detection

Scan terminal output for these patterns:

  • EADDRINUSE
  • address already in use
  • Port XXXX is already in use
  • bind: address already in use
  • OSError: [Errno 98] Address already in use

Extract the port number from the error message.

Diagnosis

Find what's using the port:

lsof -i :<PORT> -P -n

This shows the PID, process name, and user. Common culprits:

  • A previous dev server that didn't shut down cleanly
  • Another project's dev server
  • A Docker container
  • A system service

Resolution Options

Option 1: Kill the blocking process
kill <PID>
# If it doesn't stop:
kill -9 <PID>

Then restart the original server.

Option 2: Use a different port

Suggest the next available port:

# Check if port+1 is free
lsof -i :<PORT+1> -P -n

Update the dev server config or start command:

  • Next.js: next dev -p <PORT>
  • Vite: vite --port <PORT>
  • Express: set PORT env var
  • Django: python manage.py runserver <PORT>
Option 3: Kill all node processes (nuclear option)
killall node

Only suggest this if the user confirms — it kills everything.

Tips

  • On macOS, ports below 1024 require root
  • Docker containers bind ports that persist even if the container is stopped — check docker ps
  • If lsof shows nothing, the port may be in TIME_WAIT state — just wait 30 seconds or use a different port

Comments

Markdown supported