Repository navigation
Port conflict handling is not user-friendly (should fallback or guide user) #169
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.
Activity
fix(aw-server): detect if ActivityWatch is already running on AddrInUse
fix(aw-server): detect if ActivityWatch is already running on AddrInUse
docs(faq): add port-already-in-use troubleshooting entry (#191)
TimeToBuildBob commentedon Oct 6, 2026
Closing as the documentation fix is in place via #191.
What was done: PR #191 added a troubleshooting FAQ entry covering:
ss/lsof, macOS:lsof, Windows:netstat)One caveat: The merged FAQ includes a note saying "As of aw-server-rust 0.14, the server detects when another ActivityWatch instance is already listening on the port and prints a clearer message..." — however, ActivityWatch/aw-server-rust#773 (the PR that implements this detection) is still open and was not included in v0.14.0. That note is currently inaccurate. The FAQ entry is still useful as-is (the manual commands help), but the aw-server-rust claim should be updated once ActivityWatch/aw-server-rust#773 merges.
TimeToBuildBob commentedon Oct 6, 2026
PR #191 has merged, adding a troubleshooting FAQ entry that covers:
ss/lsof, macOS:lsof, Windows:netstat)This addresses the "guide user" aspect of the issue.
One caveat: The merged FAQ includes a note saying "As of aw-server-rust 0.14, the server detects when another ActivityWatch instance is already listening on the port and prints a clearer message..." — however, ActivityWatch/aw-server-rust#773 (the PR implementing this detection) is still open and was not included in v0.14.0. That note is currently inaccurate. A maintainer may want to update the FAQ note once ActivityWatch/aw-server-rust#773 merges, or close this issue if the current documentation is sufficient.
fix(aw-server): detect if ActivityWatch is already running on AddrInUse
fix(aw-server): detect if ActivityWatch is already running on AddrInUse
TimeToBuildBob commentedon Oct 13, 2026
The troubleshooting FAQ entry for port 5600 conflicts (check if AW is already running, per-OS commands to find the process, how to use a different port) landed in #191. Closing; a startup fallback or in-app guidance would be a separate server/aw-qt issue.
fix(aw-server): detect if ActivityWatch is already running on AddrInU…