ActivityWatch / ActivityWatch/docs

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

Open
#169 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
31
Forks
84
Avg merge
12d 5h
Merged PRs (30d)
2

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.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.