| name | troubleshoot-hermes-mobile-connectivity |
| description | Diagnoses Hermes Mobile "can't reach your computer" errors, pairing failures, and misleading connectivity banners. Use when the phone shows unreachable Mac/Hermes, pairing fails (localIp missing), LAN URLs (10.x/192.168.x) fail on cellular/5G, or sends timeout after 60–120s. Repo mac-yolo-safeguards / hermes-mobile. |
Troubleshoot Hermes Mobile connectivity
Symptom → likely cause (check in order)
| Symptom | Likely cause | Not the cause |
|---|
Banner: "can't reach Hermes/computer" + gateway is 10.x or 192.168.x | Phone off same Wi‑Fi (5G/cellular, different network) | Random app bug |
Pairing: Gateway health missing localIp | Gateway /health no longer returns local_ip | Phone USB broken |
| Header shows computer IP but send fails | LAN-only URL unreachable from phone network | session_in_use (different message) |
| Works on Mac mini IP, fails after reinstall | Fresh install + pair pushed this Mac's LAN IP, not saved profile | Stale APK |
Evidence commands (run all; paste outputs)
node tools/agent-session-start.js
adb devices
curl -sf -m 3 http://127.0.0.1:8642/health
curl -sf -m 3 http://<gateway-host-from-screenshot>:8642/health
node tools/hermes-mobile-pair.js
On Mac, also:
xcrun simctl list runtimes
ipconfig getifaddr en0 2>/dev/null
Decision tree
Phone gateway URL private LAN (10.x / 192.168.x / *.local)?
├─ YES → Phone on same Wi‑Fi as that host?
│ ├─ NO → REAL connectivity failure. Fix: same Wi‑Fi, Switch computer, or tunnel URL (Settings → Advanced).
│ └─ YES → curl /health from Mac; if OK, check API key / chat errors (operational, not connectivity).
└─ NO (https tunnel / public host) → curl /health; check tunnel process + API key.
Code map (where copy & logic live)
| Area | Path |
|---|
| User-facing unreachable copy | hermes-mobile/src/utils/chatErrors.ts → friendlyMacUnreachableMessage |
| LAN URL detection | hermes-mobile/src/utils/gatewayEndpoint.ts → isPrivateLanGatewayUrl |
| Send blocked when Mac down | hermes-mobile/src/screens/ChatScreen.tsx → macChatLive, sendUserText |
| Failed send banner (timer) | hermes-mobile/src/components/RunProgressBanner.tsx |
| Mac pair + LAN fallback | tools/hermes-mobile-pair.js → resolveLanIp |
| Saved computers / offline | hermes-mobile/src/components/ChatConnectionPanel.tsx, GatewayProfilePicker |
Connectivity vs operational: humanizeChatError → kind: 'connectivity' only for network markers (failed to fetch, timeout, econnrefused). session_in_use, session_not_found, invalid_api_key are operational — never label those "can't reach Mac".
Fix playbook
- Wrong network: User on 5G + paired
10.2.29.103 → explain Wi‑Fi-only; do not claim bug.
- Pair after reinstall:
adb devices → node tools/hermes-mobile-pair.js. If localIp missing, pair script uses resolveLanIp from network interfaces.
- Wrong computer: Switch to saved Mac mini profile or re-pair target host.
- Away from home: Tunnel URL in Settings — pair script cannot invent a tunnel.
- Copy fix: For LAN URLs, message must say home Wi‑Fi only / same network / tunnel — not generic "Hermes unreachable".
Install after fix
cd hermes-mobile
npm test -- --testPathPattern="chatErrors|gatewayEndpoint" --maxWorkers=1
HERMES_MOBILE_FORCE_BUILD=1 bash scripts/install-phone-release.sh
If INSTALL_FAILED_UPDATE_INCOMPATIBLE: adb uninstall com.iganapolsky.hermesmobile then reinstall (wipes app data — re-pair after).
Report format
| Check | Result | Evidence |
|---|
| Gateway /health on localhost | | curl output |
| Gateway /health at paired host (from Mac) | | curl output |
| Phone network vs URL type | LAN + cellular? | screenshot / user |
| Pair script | | exit code + last line |
| Error class | connectivity / operational | humanizeChatError kind |
Do not say "fixed" until send succeeds on device or honest blocker is stated.
