Troubleshooting
For people and agents when setup or a call goes wrong. Find the symptom, then do what the last column says.
| Symptom | Likely cause | What to do |
|---|---|---|
| The app shows no Hither tools | The server isn't added, is off, or the app hasn't reloaded | Add https://hither.dev/mcp from apps, turn it on, and reload the app. |
| Sign-in fails or loops | Wrong address, an old app, or an unsupported OAuth mode | Check the address is exactly https://hither.dev/mcp, update the app and reconnect. See OAuth details. Never put a token in a connector. |
invalid_grant with reconnect_required | The OAuth authorization ended | Sign in again. The computer is fine. |
devices is empty or the computer never appears | Approval isn't finished, or the helper isn't running | Ask the person to finish approving. hither status on the computer shows the helper. |
| The setup link expired | It passed its time limit | Get a new one: connect_computer again, or POST /api/connect/request with the same agent token. |
permission_required or device_operation_not_allowed | The connection doesn't allow that operation or folder | Tell the person which permission the task needs. They change it in the dashboard or on the setup page. |
connection_limit_or_identity_expired | An anonymous agent has 5 live connections or made 20 today, or its REST token expired | Finish or drop a connection, or wait. A REST agent past 24 hours starts again only if the person asks. |
account_agent_required or anonymous_oauth_required | Only an account agent can ask to keep access, and only an anonymous MCP agent can be claimed | See keep access. A REST agent can't do either. |
extension_unavailable_or_update_helper | The connection ended too long ago, ended another way, or the helper predates this feature | Tell the person. They can run setup again on the computer to update the helper. |
sandbox.blocked: true | The Terminal sandbox refused a write, a credential read or a local address | Tell the person what stderr says was refused. Only they can allow full access. |
update_helper_for_* | The helper is older than the feature | Ask the person to run setup again on the computer. |
device_offline | The computer is asleep or offline | Drop the work or queue it. |
outcome_unknown | The call may have run | Don't retry. Resolve it. |
401 unauthorized | The credential expired or was revoked | OAuth: let the client refresh, or sign in again. REST: the 24-hour token ended, so start again only if the person asks. |
browser_installing | Chromium is still downloading | Wait a few seconds and call again. |
HTTP 403, Cloudflare 1010 | Cloudflare blocked the client | Send a User-Agent that names your agent. Details. |
Still stuck? With the person's approval, report it.