Troubleshooting
Troubleshooting
| Issue | Solution |
|---|---|
| MCP server not found | Restart Claude Code after setup |
| Provider not authenticated | Codex: codex login (ChatGPT subscription; codex login --device-auth on a remote or headless machine), CODEX_ACCESS_TOKEN (ChatGPT Business/Enterprise), or export CODEX_API_KEY when there is neither; OPENAI_API_KEY is never used. Gemini: export GEMINI_API_KEY (a Google AI Studio key), or for the opt-in agy path run agy once. Grok: export XAI_API_KEY (else calls return errorKind: missing-auth) |
tool "ask-grok" timed out after 60s from the host, or a timeout result naming MCP_TOOL_TIMEOUT=60000 (Claude Code on the web) |
The host exports MCP_TOOL_TIMEOUT=60000. The current manifest overrides it per server ("timeout": 1800000 + env mirror), so either message means the plugin install predates that manifest: claude plugin update deliberation@antonbabenko, start a new session. Hand-written .mcp.json: add "timeout": 1800000 and "env": {"MCP_TOOL_TIMEOUT": "1800000"} to the entry. /deliberation:doctor reports it. See Timeouts |
GPT returns errorKind: "auth" with refresh token was already used / has expired / was revoked |
The auth.json in use was copied from another machine, and one of the copies refreshed first (a ChatGPT refresh token works once), or the login expired. Give each machine its own login: the next GPT call starts codex login --device-auth and shows its link and code (see "Login on first use"), or set CODEX_ACCESS_TOKEN (Business/Enterprise). A seeded secret must come from a login used for nothing else and must be re-seeded after its first refresh. See "One login per machine" under Environment variables |
deliberation-gemini shows CONNECTION_CLOSED (Claude Code on the web) |
No agy in the container and no Gemini key: the standalone Gemini bridge refuses to start rather than advertise tools it cannot serve. Export GEMINI_API_KEY and it starts and answers advisory calls over the API. The unified server keeps working and lists gemini under panel.unavailable; /consensus and /ask-all run on the remaining providers |
panel lists a provider under unavailable |
Its stat-only health check failed; the reason names the missing piece (CLI on PATH, credential). Fix that and call again - nothing is cached |
| Tool not appearing | Run claude mcp list and verify registration |
| Expert not triggered | Ask explicitly: "Ask GPT to review...", "Ask Gemini to review...", or "Ask Grok to review..." |
An advisory Gemini run returned workspaceMutated: true |
The delegate wrote to the consulted repo despite read-only mode (the OS sandbox is macOS-only; Linux relies on detection). Nothing was auto-reverted - review git status / git log and discard unwanted changes. Treat that result as tainted. |
Advisory Gemini run errors with a sandbox-exec failure on macOS |
The Seatbelt wrapper could not start. Set DELIBERATION_DISABLE_OS_SANDBOX=1 to fall back to prompt-guard + detection while investigating. |
agy print mode does not enforce folder trust, so there is no trust prompt to clear. Soft-timeout recovery (stdout-drain) is documented in Gemini timeout recovery.