agents
Agent troubleshooting
The failures we actually see, and what fixes each one.
Last updated 2026-07-10
Connection
| Symptom | Cause | Fix |
|---|---|---|
run cadenza connect first | No linked key on this machine | Run npx cadenza connect and approve in the browser |
| Approval page never loads | Grant expired (10 minute TTL) | Re-run connect; approve promptly |
| 401 on every call | Key revoked or expired | Reconnect; check your account's connections |
| 403 with a scope message | Key approved with fewer scopes than the tool needs | Reconnect and approve the needed scopes |
Tools
| Symptom | Cause | Fix |
|---|---|---|
blocked outcome | Safety policy refused the content | Read the reason; political content and unconsented likeness are not generatable |
render_failed | Every routable model failed | Rare; retry, and check /build for incident notes |
| Tools missing from the client | Config not loaded | Restart the client session after installing |
Run the doctor
terminal
npx cadenza doctorIt checks four things in one pass: the Node runtime, API reachability, whether the stored key is still accepted by the server, and which agent clients have the Cadenza MCP server installed. npx cadenza disconnect removes the stored key from the machine.
Still stuck
Check the build board for the current state of remote endpoints, and reach out through the beta channel you joined with.