Troubleshooting
5 min read
Troubleshooting
Reference document -- use when things break.
Installation and Setup Issues
"claude: command not found"
Cause: Claude Code is not installed globally or not in your PATH.
Fix:
npm install -g @anthropic-ai/claude-codeIf that still fails:
# Find where npm installs global packagesnpm config get prefix# Add that path + /bin to your PATH in ~/.zshrc or ~/.bashrc"bd: command not found"
Cause: Beads is not installed or not in your PATH.
Fix:
# Try Homebrewbrew install beads # Or npmnpm install -g @beads/bdMCP server shows disconnected in /mcp
Cause: The MCP server is not running or misconfigured.
Fix:
# Remove and re-addclaude mcp remove context7claude mcp add --transport http --scope user context7 https://mcp.context7.com/mcp # Verifyclaude/mcpIf using the local server:
claude mcp remove context7claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latestAuthentication fails
Fix:
# Re-authenticateclaude auth loginIf that does not work:
# Clear auth and start freshclaude auth logoutclaude# Follow the authentication prompts againPlugins not appearing in /plugin list
Fix:
claude/plugin marketplace add VoltAgent/awesome-claude-code-subagents/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skillIf the marketplace is unreachable, check your internet connection and try again.
Build Issues
Claude keeps making the same mistake over and over
Cause: Almost always a context problem. Claude has too much (or conflicting) context.
Fix:
Type /context — is usage above 50%?
If yes: /clear and start fresh
Re-read the implementation plan step yourself
Give Claude a very specific, constrained instruction (not "keep trying")
If the problem is architectural, check the relevant ADR — Claude may be contradicting a decision
Claude forgets what was built earlier in the session
Cause: Context overflow or auto-compaction removed important information.
Fix:
/clear
At the start of the fresh session, tell Claude:
Read CLAUDE.md, then read the implementation plan at /docs/implementation-plan.md. We are on Phase [N], Step [X]. The previous steps have been completed. Read the code in [relevant files] to understand the current state.This gives Claude the information from disk instead of relying on chat history.
Claude wrote code that breaks existing tests
Fix:
/rewind — this undoes both the conversation and code changes
Give Claude more explicit instructions:
Before making any changes to [file], read and understand the existing tests in [test file]. Your changes must not break any existing tests. If your approach would require changing existing tests, explain why before making changes.Build hangs or Claude stops responding
Fix:
Press Ctrl+C to interrupt
Type /status to check the session state
If the session is broken, exit and restart:
/exitclaudeClaude suggests libraries or APIs that don't exist
Cause: Hallucination. Claude is guessing instead of checking.
Fix:
Stop. Before using that library, check Context7 to verify it exists and confirm the correct API. Do not guess.If Context7 cannot find it:
That library does not appear to exist in Context7. Search for the official documentation using your web tools, or suggest an alternative that you can verify exists.Git Issues
Accidentally committed to main
Fix:
# Undo the last commit (keep the changes staged)git reset --soft HEAD~1 # Create a branch from the current stategit checkout -b feature/my-feature # Commit on the new branchgit commit -m "feat: my changes"Merge conflict between branches
Fix:
There are merge conflicts in [file(s)]. Show me the conflicts and help me resolve them. Prefer the changes from [branch name] unless there is a good reason to keep both.Need to undo all changes from a phase
Fix:
# Switch to maingit checkout main # Delete the feature branchgit branch -D feature/phase-N-description # Start freshgit checkout -b feature/phase-N-descriptionContext Issues
Auto-compaction happened at a bad time
Cause: Context hit ~85% and auto-compacted, possibly losing important information.
Fix:
Do not panic — CLAUDE.md and your files on disk are unaffected
Check what Claude remembers:
Summarise what you know about the current state of this project and what we were working on.If it lost important context, reload from disk:
Read CLAUDE.md, then read [the specific files we were working on]. We were working on [describe the task].Prevention: Always compact manually before 60%. Never let context reach auto-compaction.
**CLAUDE.md** is not loading
Fix:
Check the file exists: ls -la `CLAUDE.md`
Check you are in the right directory: pwd
Run Claude Code from the project root: cd /path/to/project && claude
CLAUDE.md must be at the project root OR at .claude/CLAUDE.md
Claude in Chrome Issues
Extension not connecting
Fix:
Make sure you are using Chrome or Edge (not Brave, Arc, Firefox, Safari)
Check the extension is enabled: Chrome → Settings → Extensions
Sign out and sign back in to the extension
Try removing and re-installing the extension
Claude cannot see the page content
Fix:
Reload the page
Make sure the page is not behind a login wall Claude cannot access
For localhost, make sure the dev server is actually running
Beads is unavailable, broken, or returning errors
Cause: Beads may have a breaking update, the database may be corrupted, or the hooks may have broken silently after a Claude Code update.
Immediate check:
bd versionbd statusIf either command fails or returns unexpected output:
Step 1: Check hooks are still installed:
bd setup claude --checkIf hooks are broken, reinstall them:
bd setup claudeStep 2: If Beads itself is broken, use this temporary fallback:
Prompt: Please create a /docs/tasks.md at the project root as a manual task tracker:
## Current Phase Tasks- [ ] Phase N: [description] — branch: feature/phase-N-description - Delivers: US-001, US-002 - ACs: AC-001.1, AC-001.2, AC-002.1 - Status: in progress / complete - Notes: [any relevant context]
2. Update this file manually between phases3. When Beads is restored, recreate issues from this file using `bd create`4. Reinstall hooks with `bd setup claude`Step 3: If the Beads database is corrupted:
# Back up the current databasecp .beads/beads.db .beads/beads.db.backup
# Reinitialiserm .beads/beads.dbbd init
# Recreate issues from /docs/tasks.md or your implementation planPrevention: After any Beads or Claude Code update, run bd setup claude --check to verify hooks are still intact. Hooks can break silently - there is no visible error when they stop firing.
When to Abandon the Session" Heuristic
When to Start Fresh Instead of Debugging
Sometimes the fastest fix is to stop trying to fix the current session and start over. Use these triggers:
Start a fresh session if ANY of these are true:
Claude has attempted the same fix 3+ times without progress. If the same approach has failed three times, more context will not help — the approach is wrong.
You have spent more than 15 minutes on a single error without clear movement toward a solution. The context window is getting polluted with failed attempts, which makes each subsequent attempt worse.
Claude is contradicting its own previous output within the same session. This means context is too full or conflicting information is confusing the model. No amount of prompting will fix this — only a clean context will.
Claude is generating code that looks noticeably worse than earlier in the session. Quality degradation mid-session is almost always a context problem.
The recovery procedure:
Commit whatever currently works (even if incomplete): git add -A && git commit -m "wip: saving progress before fresh session"
Note which step in the implementation plan you were on
/exit to close Claude Code
Reopen claude
Start with this prompt:
Read CLAUDE.md and the implementation plan at /docs/implementation-plan.md. We are on Phase [N]. Read the current code in [relevant files] to understand what has been built so far. The previous session got stuck on [describe the specific problem]. Approach this differently — [suggest a different angle if you have one, or say "propose an alternative approach"].Do NOT paste the error messages from the failed session, they will bias Claude toward the same broken approach
Key insight: A fresh session with a clean context and a slightly different framing will almost always solve a problem faster than continuing to fight a polluted context. Starting fresh is not failure, it is the correct recovery action.
Getting more help
If none of the above fixes your issue:
Run claude /doctor and note any errors
Check the Claude Code GitHub issues: https://github.com/anthropics/claude-code/issues
Check your Claude Code version: claude --version and compare to the latest release
Try updating: npm update -g @anthropic-ai/claude-code
As a last resort, uninstall and reinstall:
npm uninstall -g @anthropic-ai/claude-codenpm install -g @anthropic-ai/claude-codeclaude /doctorSign up to read the full guide
Free access to all 12 workflow guides. No password needed.