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-code

If that still fails:

# Find where npm installs global packages
npm 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 Homebrew
brew install beads # Or npm
npm install -g @beads/bd

MCP server shows disconnected in /mcp

Cause: The MCP server is not running or misconfigured.

Fix:

# Remove and re-add
claude mcp remove context7
claude mcp add --transport http --scope user context7 https://mcp.context7.com/mcp # Verify
claude
/mcp

If using the local server:

claude mcp remove context7
claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp@latest

Authentication fails

Fix:

# Re-authenticate
claude auth login

If that does not work:

# Clear auth and start fresh
claude auth logout
claude
# Follow the authentication prompts again

Plugins not appearing in /plugin list

Fix:

claude
/plugin marketplace add VoltAgent/awesome-claude-code-subagents
/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill

If 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:

1. Type /context — is usage above 50%?

2. If yes: /clear and start fresh

3. Re-read the implementation plan step yourself

4. Give Claude a very specific, constrained instruction (not "keep trying")

5. 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:

1. /clear

2. 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:

1. /rewind — this undoes both the conversation and code changes

2. 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:

1. Press Ctrl+C to interrupt

2. Type /status to check the session state

3. If the session is broken, exit and restart:

/exit
claude

Claude 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 state
git checkout -b feature/my-feature # Commit on the new branch
git 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 main
git checkout main # Delete the feature branch
git branch -D feature/phase-N-description # Start fresh
git checkout -b feature/phase-N-description

Context Issues

Auto-compaction happened at a bad time

Cause: Context hit ~85% and auto-compacted, possibly losing important information.

Fix:

1. Do not panic — CLAUDE.md and your files on disk are unaffected

2. Check what Claude remembers:

Summarise what you know about the current state of this project and what we were working on.

1. 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:

1. Check the file exists: ls -la `CLAUDE.md`

2. Check you are in the right directory: pwd

3. Run Claude Code from the project root: cd /path/to/project && claude

4. CLAUDE.md must be at the project root OR at .claude/CLAUDE.md

Claude in Chrome Issues

Extension not connecting

Fix:

1. Make sure you are using Chrome or Edge (not Brave, Arc, Firefox, Safari)

2. Check the extension is enabled: Chrome → Settings → Extensions

3. Sign out and sign back in to the extension

4. Try removing and re-installing the extension

Claude cannot see the page content

Fix:

1. Reload the page

2. Make sure the page is not behind a login wall Claude cannot access

3. 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 version
bd status

If either command fails or returns unexpected output:

Step 1: Check hooks are still installed:

bd setup claude --check

If hooks are broken, reinstall them:

bd setup claude

Step 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 phases
3. 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 database
cp .beads/beads.db .beads/beads.db.backup

# Reinitialise
rm .beads/beads.db
bd init

# Recreate issues from /docs/tasks.md or your implementation plan

Prevention: 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:

1. 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.

2. 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.

3. 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.

4. 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:

1. Commit whatever currently works (even if incomplete): git add -A && git commit -m "wip: saving progress before fresh session"

2. Note which step in the implementation plan you were on

3. /exit to close Claude Code

4. Reopen claude

5. 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:

1. Run claude /doctor and note any errors

2. Check the Claude Code GitHub issues: https://github.com/anthropics/claude-code/issues

3. Check your Claude Code version: claude --version and compare to the latest release

4. Try updating: npm update -g @anthropic-ai/claude-code

5. As a last resort, uninstall and reinstall:

npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code
claude /doctor