Create wiki page 'Troubleshooting'

2026-05-14 19:44:56 +00:00
parent a34d2897bd
commit f6a1aa5988
1 changed files with 111 additions and 0 deletions
@@ -0,0 +1,111 @@
+# 🔧 Troubleshooting
+
+Common problems and their solutions.
+
+---
+
+## `[Errno 48] Address already in use`
+
+Port 8000 or 8765 is already occupied.
+
+```bash
+# Kill whatever is using port 8000
+lsof -ti :8000 | xargs kill -9
+
+# Kill whatever is using port 8765 (auth wizard port)
+lsof -ti :8765 | xargs kill -9
+```
+
+---
+
+## `401 Unauthorized`
+
+Your access token has expired or your refresh token is no longer valid.
+
+**Fix:** Re-authenticate:
+```bash
+uvx --from strava-mcp-server-hnrx auth
+```
+
+---
+
+## `❌ Missing STRAVA_CLIENT_ID or STRAVA_CLIENT_SECRET`
+
+The server cannot find your credentials.
+
+**Causes:**
+- You haven't run `auth` yet
+- The config file is in an unexpected location
+- You're running from a directory with an incomplete `.env` file
+
+**Fix:**
+```bash
+# Run the interactive setup wizard
+uvx --from strava-mcp-server-hnrx auth
+
+# Verify the config file exists
+cat ~/.config/strava-mcp-server/config.env
+```
+
+---
+
+## `ℹ️ No STRAVA_REFRESH_TOKEN found. Server starting in unauthenticated mode.`
+
+The server can start without a refresh token, but all Strava API calls will fail.
+
+**Fix:** Run `auth` to complete the OAuth flow and generate a refresh token.
+
+---
+
+## Server starts but tools return errors
+
+**Check 1:** Is your Strava app authorized?
+```bash
+# Re-run auth to refresh all tokens
+uvx --from strava-mcp-server-hnrx auth
+```
+
+**Check 2:** Does your Strava API app have the right scopes?
+The `auth` command requests: `profile:read_all,activity:read_all,activity:read,profile:write`
+
+If you initially authorized with fewer scopes, re-run `auth` with `approval_prompt=force` (this happens automatically).
+
+---
+
+## `uv run auth` command not found
+
+The commands are not registered in the virtual environment.
+
+**Fix:**
+```bash
+rm -rf .venv && uv sync
+```
+
+---
+
+## Config file not found after `uvx` run
+
+`uvx` runs the package in an isolated environment, so it looks for config in `~/.config/strava-mcp-server/config.env`, not a local `.env`.
+
+**Fix:**
+```bash
+# Ensure auth was run via uvx (not uv run)
+uvx --from strava-mcp-server-hnrx auth
+
+# Verify the file was created
+ls ~/.config/strava-mcp-server/
+```
+
+---
+
+## SSE Health Check
+
+Verify the HTTP server is responding:
+```bash
+curl -v -X POST http://localhost:8000/mcp
+```
+Expected: An SSE stream starting with `event: endpoint`.
+
+---
+
+*Back to [Home](Home)*