mcpField
D
detecting-port-conflicts

detecting-port-conflicts

github.com/revitalb-portDevelopment069 installsUpdated 11w ago
Repository

About detecting-port-conflicts

A troubleshooting skill for diagnosing why a development server cannot start because its port is occupied. It guides developers through identifying the process and either stopping it or switching ports.

Key features

  1. 01Recognizes common port-in-use errors
  2. 02Finds process details with lsof
  3. 03Offers process termination or port change
  4. 04Covers Docker and TIME_WAIT cases

Use cases

  1. 01Investigating a dev server startup failure
  2. 02Choosing whether to stop a process or use another port

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/revitalb-port/skills-registry-demo --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