Port conflict handling is not user-friendly (should fallback or guide user)
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Feature
- Clarity
- Needs clarification
- Activity status
- Quiet
- Domain
- backend
Research direction
No implementation files, tests, or entry points are named. Start by locating the ActivityWatch startup code that binds port 5600, then clarify with maintainers whether automatic fallback or actionable conflict guidance is preferred. Done should include the chosen behavior, clear user-facing resolution, and coverage for an occupied port.
Written by the indexing model from the issue text.
Description
ActivityWatch Port Conflict Handling
📄 Description
When port 5600 is already in use, ActivityWatch fails to start and shows:
Address already in use
Port 5600 is in use by another program. Either identify and stop that program, or start the server with a different port.
This creates confusion because:
- The user cannot tell what is using the port
- No automatic fallback is attempted
- No guidance is provided
💡 Suggested Improvements
-
Detect if port is already in use
-
Either:
-
Automatically select the next available port (e.g. 5601, 5602)
-
OR clearly show:
- Which process is using the port
- How to resolve it
-
Optional Enhancements
- Allow configurable default port
🎯 Why? very important to the end user and is a part of UX design
⚔️ When Does This Happen?
✅ Case 1: ActivityWatch already running
Most common case.
You tried to start it again → conflict occurs.
⚠️ Case 2: Another application using the port
Rare, but possible.
Any application can bind to any free port.
🔁 Case 3: Previous instance didn’t shut down properly
A leftover (zombie) process is still holding the port.
🙋 Contribution
I’d be interested in working on this if the approach aligns with the project direction.
- Dominant language
- Python
- Stars
- 31
- Forks
- 84
- Avg merge
- 11h 45m
- Merged PRs (30d)
- 4
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from ActivityWatch/docs
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
ActivityWatch/docs#184 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
ActivityWatch/docs#143 · 2 comments ·
-
Difficulty 3/5 1-2 days Newbie friendliness 55/100
ActivityWatch/docs#179 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 55/100
ActivityWatch/docs#170 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 35/100
ActivityWatch/docs#136 · 1 comment ·
All issues in ActivityWatch/docs
Similar issues
-
essnmx good first issue
Difficulty 1/5 Under an hour Newbie friendliness 95/100
-
[Feature] 奇物选择添加优先级 Open
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
syfoud/Simulated_Scepter#174 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Giskard-AI/giskard-oss#2840 · 1 comment ·
-
A claim comment carrying the issue number is silently declined while the workflow reports success Openarea: repo bug perceived difficulty: 2
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
yeti-platform/yeti#1380 ·