Port conflict handling is not user-friendly (should fallback or guide user)

[ShiwamKumar2208]

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.