Troubleshooting & FAQ
Connection
| Symptom | Fix |
|---|---|
401 unauthorized on every call |
IDE clients: complete the GitHub sign-in your client opens (in
Claude Code run /mcp → Authenticate); if it loops, clear
the saved credentials for botz and reconnect. Headless/CI:
send a valid bzt_ API key as
Authorization: Bearer — see
Headless & CI. Never paste keys
into chat. |
| Client can't connect at all | Confirm the URL ends with /mcp and your client uses
the streamable HTTP transport. Legacy SSE-only clients need the
operator to enable the compatibility endpoint. |
| Tools missing / fewer than 12 | Your client cached an old tool list — reconnect or restart the client. |
Requesting skills
| Symptom | Fix |
|---|---|
action: "clarify" keeps coming back |
Your brief is still too thin. Answer all the questions in
one string via the answers parameter — concrete
input/output examples matter most. |
action: "rejected" (near-duplicate) |
A skill covering this already exists — the response names it. Use that skill instead of re-requesting. |
| Creation feels slow | Deployments running a local model author skills in minutes, not seconds. Your agent can continue other work while it completes. |
| Generated skill is a draft | The deployment runs with quarantine on: an operator reviews and promotes drafts in the management console. |
Feedback & updates
| Symptom | Fix |
|---|---|
Feedback accepted: false |
Anti-gaming gate: you can only vote shortly after loading the skill, once per day. Not an error — no action needed. |
Pinned version won't load (no snapshot vN) |
The pin predates recorded history. Load the latest, re-pin, and note that the skill advanced. |
skill_updates says unknown |
The artifact was retired. Keep using your pinned snapshot if it still loads; otherwise search for a replacement. |
Reading results
| Symptom | Fix |
|---|---|
Body looks like symbols (⟦CRUX:…⟧) |
That's the compressed serving format — see
Reading CRUX. Agents read it directly;
humans can request raw=true. |
Response flagged low_pr |
The platform has low confidence in that result — verify before relying on it. |
Still stuck?
Your deployment's operator can see live diagnostics and logs in the test
console (/) and management console (/admin) of the
server you're connected to.