Troubleshooting
Check connection, version, approval and output problems in order.
On this page
Workflow
Check that the local broker runs, the console is paired and the MCP client points to the active installation. If tools are missing, inspect the plugin or stdio configuration in a new chat; do not expose a public port to fix local connectivity.
Boundary and checks
On approval failure, inspect state, expiry and configuration version. Verify a changed SSH fingerprint through a trusted channel rather than disabling checks. Continue truncated output from its cursor; after network timeout, inspect the remote state before retrying.
Diagnose the stage that failed
| Symptom | Check first |
|---|---|
| Management page unavailable | Run status with the active binary; use open on the broker’s computer, not a public port |
| Initial pairing link expired | Before PIN setup, run open for a new one-time link instead of refreshing the old one |
| MCP tools missing | Check the client’s active absolute binary path, matching data directory and stdio support; reload and call the read-only capability tool |
| Credential store unavailable | Unlock or repair the OS store; do not switch to cleartext files or turn off OS protection |
| SSH host rejected | Verify address, port and fingerprint through an independent trusted source; never accept an unexplained change |
| Approval unusable | Inspect expiry, state, one-time consumption and target/template/credential version changes |
| Output truncated | Continue with the returned cursor inside the retention window; rerunning a task cannot recover rotated-out output safely |
| Timeout or disconnect | Inspect the original run, target system and stable error code before deciding whether to request again |
Keep security controls in place
A failed connection test does not justify disabling TLS, skipping SSH host verification or expanding account privileges. HTTP testing uses HEAD only; a rejected HEAD does not rule out a working business API. For database cleanup_ok:false, inspect the remote session. A Git push or file overwrite may already have committed; stopping locally cannot undo it.
For ordinary defects, include product version, platform, installation method and a sanitized minimal reproduction with cleanup result. Never send a password, PIN, recovery key, private business endpoint, personal path or unreviewed raw log. Report a possible vulnerability privately. Related guides: installation, clients, approvals and backup.
Corresponding product documentation · Report a documentation issue