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).
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.

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).