detecting-port-conflicts

Q: How do I install detecting-port-conflicts?

Run npx skills add https://github.com/spencerpauly/awesome-cursor-skills --skill detecting-port-conflicts in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/detecting-port-conflicts/ (personal) or .claude/skills/detecting-port-conflicts/ (project).

by spencerpauly

Detect EADDRINUSE and port conflicts, find what's using the port, and resolve it by killing the process or suggesting an alternative port.

Installs: 422
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

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

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads detecting-port-conflicts automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

FAQ

What does the detecting-port-conflicts skill do?

Detect EADDRINUSE and port conflicts, find what's using the port, and resolve it by killing the process or suggesting an alternative port.

How do I install detecting-port-conflicts?

Run npx skills add https://github.com/spencerpauly/awesome-cursor-skills --skill detecting-port-conflicts in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/detecting-port-conflicts/ (personal) or .claude/skills/detecting-port-conflicts/ (project).

Which AI agents can use detecting-port-conflicts?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is detecting-port-conflicts safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains detecting-port-conflicts?

It is published by spencerpauly in spencerpauly/awesome-cursor-skills. It has 422 recorded installs.