Troubleshooting
The failure modes you are most likely to hit, and the exact thing to check for each.
All
Phone cannot find the computer
- 1Confirm both devices are on the same Wi-Fi. Guest networks and AP/client isolation block discovery and direct HTTP.
- 2On iPhone, check that Local Network permission is Allowed. The empty-state card shows Allowed / Denied / Not granted explicitly.
- 3Make sure the desktop app is actually running. On macOS check the menu bar; on Windows check the tray.
- 4Confirm the port. The service defaults to 8787 but falls back to 8788 or 8789 — run brewping status, or read the port from the tray / menu bar.
- 5Allow the port through any firewall on the computer.
- 6Add the device manually by IP instead of relying on discovery.
Pairing fails
| Symptom | Cause and fix |
|---|---|
| Invalid or expired pairing code | Codes live 600 seconds. Generate a new one on the computer and retry. |
| Code rejected on a second phone | Codes are single-use. Regenerate for each device. |
| Time skew errors | Write requests need a timestamp within ±120 seconds. Check the device clock. |
| Invalid host or port | Verify the IP and the port reported by brewping status. |
| Couldn't save the pairing token to the Keychain | Re-add the device on iOS; check the device lock state and Keychain access. |
401 / 403 responses
- Missing or wrong bearer token — pair the device again.
- Write request without X-BrewPing-Timestamp or with a reused X-BrewPing-Nonce — supply a fresh nonce and a current timestamp.
- The token file was deleted or reset — re-pair from the phone.
An agent is not detected
- 1Confirm the CLI works in your own terminal: run the executable with --version.
- 2Detection uses which, so the executable must be on PATH. nvm-managed installs, /opt/homebrew/bin, /usr/local/bin and ~/.local/bin are searched.
- 3Results are cached for 60 seconds — force a refresh with POST /api/discovery/refresh, or wait a minute.
- 4On Windows, install or repair the CLI from Settings > Environment & AI CLI.
A task never finishes
- Poll GET /api/message/:id and look at the status; queued means it has not reached the terminal yet.
- If the status is failed, read failureReason — quota, authentication and timeout all have their own reasons.
- The agent process may have exited. Check brewping status and restart the session.
- Raw screen output is still returned as completed_with_raw when the result cannot be parsed.
Working directory has no effect
- The opencode entry is a stub that never spawns a process, so a working directory does nothing for it. Use claude-code, codex or pi.
- A deleted or unmounted directory produces the distinct failure code invalid_workdir rather than silently falling back elsewhere.
- On Windows, UNC paths are rejected by design.
Where to look
| Platform | Location |
|---|---|
| macOS | ~/.brewping/agent.log and ~/.brewping/opencode.log; session.json holds the current session |
| Windows | %USERPROFILE%\.brewping\ — device.json, pairing.json, model_providers.json, workdirs.json |
| iOS | Help & About shows the app version; logs go through the system logger with command text marked private |