Troubleshooting

Run the doctor first. ask-llm doctor checks Node version, PATH, every provider CLI's presence + version, and env vars. It works even when MCP can't start. Follow the failed-check remediation for your selected assistant and reviewer. Warnings about providers you do not use do not require installing them or adding API keys.

ask-llm doctor                       # human-readable
ask-llm doctor --json                # established full JSON, exit 1 on error
ask-llm doctor --format toon         # bounded, versioned agent-facing TOON pilot
ask-llm doctor --format toon --full  # full TOON escape hatch

After a global install, use ask-llm doctor for host and provider states. The optional --live check may spend provider quota; see Diagnostics / doctor for the state meanings and output formats.

Installation Issues

"Command not found: gemini" / "codex" / "ollama"

Click to see solution

Provider CLI is not installed or not on PATH

"PATH issue": CLI works in terminal but MCP server says "not found"

Click to see solution

macOS GUI apps don't inherit your shell PATH

MCP server not responding (Claude Desktop cannot connect)

Click to see solution

Server fails to start or connection drops

EUNSUPPORTEDPROTOCOL workspace:* in an earlier npx registration

Click to see solution

An earlier cached installation can fail before the server starts

Connection & Auth

"Authentication failed" / "401 Unauthorized"

Click to see solution

Provider CLI isn't authenticated

Quota / rate limit errors (Gemini RESOURCE_EXHAUSTED, Codex 429)

Click to see solution

Provider quota exhausted

"Command timed out after Xs"

Click to see solution

Provider call exceeded the per-provider wall-clock timeout

Tool & API Issues

"Provider X is not available" / tool call rejects provider

Click to see solution

The orchestrator didn't detect the provider at startup

"Sub-agent silently produces 0-byte output" / brainstorm coordinator hang

Click to see solution

Provider process killed by sub-agent lifecycle

Model & Response Issues

Response gets cut off mid-stream

Click to see solution

MCP message size limits or executor timeout

Plugin Issues

Plugin slash commands not appearing in Claude Code

Click to see solution

Plugin not installed or not loaded

Debug Mode

Enable verbose logging:

{
  "mcpServers": {
    "ask-llm": {
      "command": "/absolute/path/to/ask-llm-mcp",
      "args": [],
      "env": {
        "GMCPT_LOG_LEVEL": "debug"
      }
    }
  }
}

Logs go to stderr. Claude Desktop captures them in:

• macOS: ~/Library/Logs/Claude/mcp-server-*.log
• Linux: ~/.config/claude/logs/

Getting Help

1. Run the doctor first: ask-llm doctor
2. Check GitHub Issues for similar reports
3. Open a new issue with: doctor output, your client (Claude Code/Desktop/Cursor/etc.), Node version, OS, and what you ran
4. Ask in GitHub Discussions for usage questions