Improvement: Diagnose port conflicts by checking if the project itself is already running
Resolved 💬 2 comments Opened May 27, 2026 by mine1212design-blip Closed Jul 11, 2026
Summary
When a port conflict is detected during preview_start, Claude Code reports "port is in use by another process" without further investigation. In practice, the conflicting process is often the same project already running from a previous session or terminal.
Current Behavior
preview_startdetects port 3000 is in use- Reports: "Port 3000 is in use by another process"
- Assigns a fallback port (e.g. 60138) and starts a second instance
- User cannot access the preview — they don't realize the app was already running
Expected Behavior
- Port conflict detected
- Automatically inspect the conflicting process (PID, command line, executable path)
- If it matches the current project directory → tell the user: "This project is already running on port 3000. Open http://localhost:3000"
- Skip starting a duplicate instance
Suggested Steps
- Get PID using the port (netstat / lsof)
- Get full command line of that PID
- Compare path against current project directory
- If match: show "Already running" + URL
- If no match: report the foreign process name and path
Context
- OS: Windows 10
- Claude Code version: v2.1.152
- Reproduction: Run npm run dev in a terminal, then ask Claude Code to start the same project via preview_start
Impact
Non-engineers are confused by the port conflict error and cannot easily tell whether to stop a process or just open a browser tab.
---
Reported via Claude Code by a non-engineer user.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗