# Claude Code /advisor Troubleshooting: 8 Errors and Fixes (May 2026) > **TL;DR:** Eight errors I've hit running /advisor on real repos in April-May 2026, each with the exact message, the root cause, and the one-liner fix. Bookmark this for the next time your CLI screams at midnight.

Quick diagnostic checklist

Before grepping the table below, run these three:

claude --version                       # 2.6+ required
claude doctor                           # checks auth, MCP, hooks
echo $ANTHROPIC_API_KEY | head -c 12   # sanity-check the key

Most /advisor failures fall out of claude doctor immediately. If not, match symptoms below. For background on what /advisor actually does, see the Claude Code /advisor command deep-dive.

1. "model not found"

Error: model "claude-3-5-opus" not found
  at AdvisorCommand.resolveModel (advisor.ts:118)

Cause: Stale config pinning a retired model alias. Anthropic deprecated claude-3-5-* in February 2026.

Fix:

claude config set advisor.opus   "claude-opus-4-5"
claude config set advisor.sonnet "claude-sonnet-4-6"
claude config set advisor.haiku  "claude-haiku-4-5"

2. MCP server conflict

Error: MCP server "filesystem" returned tool with name
"read_file" already provided by server "default"

Cause: Two MCP servers registering the same tool name. /advisor aborts because tool routing is ambiguous.

Fix: Edit ~/.claude/mcp.json and either remove the duplicate or namespace one with "toolPrefix": "fs_":

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/repo"],
    "toolPrefix": "fs_"
  }
}

3. Rate limit 429

Error 429: rate_limit_error — input tokens per minute exceeded
  Retry-After: 38s

Cause: /advisor ran twice in quick succession on a large file, each scoring + acting. Pro tier hits ITPM ceilings around 80k/min.

Fix: add a backoff and a cap:

claude config set advisor.maxConcurrent 1
claude config set advisor.backoffMs 2000

4. Context window exceeded

Error: prompt is 218,402 tokens; max for sonnet-4-6 is 200000

Cause: Stuffed conversation, often after pasting log output or running /advisor on a giant file plus an active MCP doc-load.

Fix: compact the context, then retry:

/clear           # nuke the session
# OR
/compact         # summarize and retain semantic gist
# OR pin to 1M-context Opus
claude --model claude-opus-4-5-1m /advisor ...

5. Auth token expired

Error 401: authentication_error — invalid x-api-key

Cause: OAuth session expired (Pro plan) or the env var got stomped by a shell rc that overrides ANTHROPIC_API_KEY.

Fix:

claude logout
claude login        # OAuth flow opens browser
# OR for API-key users:
export ANTHROPIC_API_KEY="sk-ant-..."   # pin in .envrc / direnv

6. Invalid permission mode

Error: permission "auto-accept-all" not allowed in advisor turns

Cause: Project .claude/settings.json sets a permission mode that conflicts with /advisor's preview-then-apply contract.

Fix: drop the override. /advisor needs at least plan mode so the user can accept the recommendation:

claude config set permissionMode plan

7. Hook blocking edits

[Hook] BLOCKED: File exceeds 800 lines (842 lines)
[Hook] Split into smaller modules
Error: PreToolUse hook denied Write to scheduler.ts

Cause: A guardrail hook in ~/.claude/settings.json rejects oversized writes. /advisor respects hooks — that's the point — so it bails.

Fix: let /advisor emit the refactor plan first, accept the file split, then the writes will all pass the 800-line gate:

/advisor refactor scheduler.ts --goal "≤ 800 lines per file"

8. Shell escape issues with quotes

$ /advisor "fix the bug in 'auto-publish' job"
Error: unexpected token '

Cause: Nested single quotes break the shell tokenizer before /advisor ever sees the string.

Fix: use the heredoc form, or escape:

/advisor "fix the bug in \"auto-publish\" job"
# OR
claude <<'EOF'
/advisor fix the bug in 'auto-publish' job
EOF

Where to file bugs

Anthropic accepts /advisor issues at github.com/anthropics/claude-code/issues. Include claude doctor output, the redacted slash invocation, and your ~/.claude/settings.json. Don't paste API keys.

FAQ

Where are Claude Code logs stored?

On macOS: ~/Library/Logs/Claude/. On Linux: ~/.local/state/claude/logs/. /advisor writes a JSONL line per recommendation including model picked, score, and apply outcome.

How do I downgrade Claude Code if /advisor breaks?

Pin a known-good version: npm i -g @anthropic-ai/claude-code@2.6.0. Anthropic keeps the last six minor releases on npm.

Does /advisor count as one or two API calls?

Two. The scoring call is small (~500 input tokens, Haiku-priced) and the action call runs at the recommended tier. The scoring overhead is ~1% of session cost.

Can a hook silently break /advisor?

Yes. A PreToolUse hook that mutates tool input without echoing it back will look like a hang. Always have your hook write to stdout on success and stderr on block.

#troubleshooting

Claude Code /advisor Troubleshooting: 8 Errors and Fixes (May 2026)

#troubleshooting

Claude Code /advisor Troubleshooting: 8 Errors and Fixes (May 2026)