From 6d5e4dde6d7b75c694c41fb2bb9954b693e8c41e Mon Sep 17 00:00:00 2001
From: Bob <bob@superuserlabs.org>
Date: Fri, 2 Oct 2026 03:43:53 +0000
Subject: [PATCH] docs(faq): add port-already-in-use troubleshooting entry

Addresses ActivityWatch/docs#169: explain that 'Address already in use'
on port 5600 usually means ActivityWatch is already running, how to
check, and per-OS commands to find the blocking process.

Also notes the improved detection in aw-server-rust >= 0.14
(see ActivityWatch/aw-server-rust#773).

Git-Session-Id: a3f7
---
 src/faq.rst | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/src/faq.rst b/src/faq.rst
index 5f324d7..8e5c5cc 100644
--- a/src/faq.rst
+++ b/src/faq.rst
@@ -126,6 +126,31 @@ If the server crashes or is unavailable, watchers which use the `heartbeat <hear
 
 If a watcher crashes, its bucket will simply remain untouched until it is restarted.
 
+.. _port-already-in-use:
+
+The server fails to start: "Address already in use" or "Port 5600 is in use"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This error usually means an ActivityWatch instance is already running — for example from a previous session that was not shut down cleanly, or because ActivityWatch launched automatically at login while you were starting it manually.
+
+**Check if ActivityWatch is already running:**
+
+Open ``http://localhost:5600`` in your browser. If the ActivityWatch web interface loads, the server is already running and you can use it as-is. You can also close the duplicate launch.
+
+**If the web interface does not load**, another program has taken port 5600.
+Find it with the appropriate command for your operating system:
+
+* **Linux:** ``ss -ltnp | grep :5600`` or ``lsof -i :5600``
+* **macOS:** ``lsof -i :5600``
+* **Windows (Command Prompt):** ``netstat -ano | findstr :5600``
+
+Once you identify the process, stop it and start ActivityWatch again.
+
+.. note::
+   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
+   instead of a generic ``Address already in use`` error.
+
 ..
     What happens when my computer is off or asleep?
     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~