Troubleshooting

Resolve connection, permission and state errors before repeating a side-effecting request.

Connection checklist

Connection refused: confirm the desktop is running and use the address currently shown in API & MCP.
401: check the intended token, expiry and revocation without printing its value.
403/421: verify scopes, Origin/Host and local process use. Do not disable protection to make a website script work.
MCP tools missing: compare tools/list for that token, the installed app version and required scopes.
Browser start failed: inspect kernel availability, proxy checks and runtime error; listing profiles alone does not test a kernel.

Interpret uncertain results

A CLI exit code, HTTP status or JSON-RPC envelope is not enough for batch/import/tool success. Inspect per-item results or result.isError. For transfer previews check lifetime and token ownership. After a lost start/execute response, read local state before considering a new request.

Useful diagnostic details

Record the app/API version, method and template path, status, safe error code, request_id and whether the operation changed state. Remove bearer/provider tokens, cookies, secret response bodies, personal paths and account data. The downloadable manifest identifies this documentation snapshot; an installed version can differ.