docs/troubleshooting.md

# Troubleshooting — check here first

Every issue we actually hit, and the fix.

## Deploy / build

| Symptom | Cause → Fix |
|---------|-------------|
| `pre-receive hook declined: You are not authorized to push` | The token in the `origin` URL isn't the Space owner's. Use an `akash1313` token with `repo.write` (see [deployment.md](deployment.md)). |
| `Repository not found` on push | Remote points to a Space that doesn't exist. `git remote -v` and fix the name (we deploy to `akash1313/selfapi-v2`). |
| Build `BUILD_ERROR` after bumping a server | `go.mod` Go version > build-stage image. Raise the `FROM golang:X` in the Dockerfile. |
| Python `externally-managed-environment` during pip | Debian 12 PEP-668. We use `pip3 install --break-system-packages` (already in Dockerfile). |
| Frequent restarts | Normal: **every `git push` and every secret change rebuilds.** Batch edits into one push. Not a CPU/RAM issue (cpu-basic = 2 vCPU / 16 GB; usage ~1–2 GB). |

## API gateway

| Symptom | Cause → Fix |
|---------|-------------|
| All `/gpt /gemini /flow` return `503` | `API_KEY` not set on the server. Set the secret (fail-closed by design). |
| `401` | Missing/wrong `Authorization: Bearer <key>`. |
| `502 backend unavailable` | That server is still booting or crashed. Check its log `/home/chrome/{chatgpt,gemini,flow}.log`. |
| `404` through the gateway | Path forwarded but wrong on the backend — check the route in [../HOWTOUSE.md](../HOWTOUSE.md). |

## Runtime / browser

| Symptom | Cause → Fix |
|---------|-------------|
| Login lost after restart | `DATABASE_URL` unset or DB unreachable (HF). Set the Neon secret; verify a row in `chrome_profile`. |
| ChatGPT Cloudflare "verify you are human" loops | UA/OS mismatch. The UA **must be Linux** (the Space runs Linux) — it's set in `start_hf.sh` and `free-Chatgpt-api/cookies.go` (Chrome 145). If it still loops, it's the datacenter IP (HF=AWS) → use a residential `--proxy-server`. |
| `extensionConnected:false` / `has_flow_key:false` on `/…/health` | The in-Chrome extension hasn't connected to its server yet. It connects when (a) Chrome has loaded the extension and (b) **you're logged in** to that service. Open the monitor UI, log in, wait. Extensions auto-retry (~5 s reconnect alarm). |
| Extension never connects + API calls **hang forever** (`DidStartWorkerFail` in `chrome.log`) | Chrome was launched with renderer-capping flags (`--renderer-process-limit=1`, `--process-per-site`, `--no-zygote`). Each extension's MV3 service worker is its own renderer and the chat flow injects via `executeScript`; capping renderers starves them → workers fail to start and `executeScript` hangs. **Removed from `start_hf.sh`** — keep Chrome multi-process (HF has 16 GB). The UI chatting fine while the API hangs is the tell. |
| Backend server logs | `GET /logs/{chatgpt,gemini,flow,monitor}` (API-key gated) tails each server's log without shelling into the container. |
| `chrome://extensions/` empty, no error | Branded Chrome ignoring `--load-extension` → must use Chrome for Testing (already in Dockerfile). |
| `Failed to connect to the bus` / `DidStartWorkerFail` in `chrome.log` | Harmless container warnings — not a crash. |
| "Restore pages?" popup | Handled by the `exit_type=Normal` Preferences injection in `start_hf.sh`. |

## Self-host Docker

| Symptom | Cause → Fix |
|---------|-------------|
| Port collision on 9225/8000/8101 | Don't add separate server containers — the `chrome` image already runs all 3. `docker-compose.yml` has only the `chrome` service by design. |
| APIs return `503` locally | Add `API_KEY=…` to `.env` (compose passes it to the chrome service). |
| Profile not persisting | Don't use `down -v` (that deletes the `chrome-profile` volume). |