Troubleshooting

When stuff breaks. Here's how to fix it quickly.

The Honest Truth Up Front

This is early-stage software built for power users. Things will break. Rough edges exist.

This page helps you fix issues quickly. Still stuck after trying these? Ask in Circle - we're all figuring this out together, and someone has probably hit the same issue.

Don't suffer in silence. Document what breaks, share solutions, help improve the system.

Issue 1: "Command not found" or Tool Errors

Symptoms

• claude: command not found
• bash: git: command not found
• Tools don't work or throw errors
• Nothing happens when you run commands

Fix: Check Claude Code Installation

# Check Claude Code is installed
claude --version

# Should show version number like: claude 1.2.3

If command not found:

• Claude Code not installed → Install from claude.ai
• Not in PATH → Check installation completed
• Wrong terminal → Restart terminal after installation

Fix: Check Git Installation

# Check git is installed
git --version

# Should show version like: git version 2.39.0

If git not found:

On Mac:

xcode-select --install

On Windows: Download from git-scm.com

On Linux:

sudo apt install git  # Ubuntu/Debian
sudo yum install git  # CentOS/RHEL

Fix: Check Your PATH

# See what's in your PATH
echo $PATH

# Should include directories like:
# /usr/local/bin
# /usr/bin
# Claude Code installation directory

If missing:

Add to your shell config (~/.zshrc or ~/.bashrc):

export PATH="/usr/local/bin:$PATH"
export PATH="/path/to/claude/code:$PATH"

Then reload:

source ~/.zshrc  # or ~/.bashrc

Issue 2: Gmail/Newsletter Fetch Not Working

Symptoms

• "Failed to fetch newsletters"
• "Authentication error"
• No newsletters appearing after running check
• Gmail API errors in output

Fix: Check Credentials Exist

# Verify Google credentials file exists
ls ~/google-credentials.json

# If exists, should show file path
# If "No such file", need to create credentials

If missing:

1. Go to Google Cloud Console
2. Create new project (or select existing)
3. Enable Gmail API
4. Create OAuth 2.0 Client ID credentials
5. Download as credentials.json
6. Move to ~/google-credentials.json

See: Google's OAuth setup guide

Fix: Re-authenticate

Sometimes credentials expire or become invalid:

# Remove existing token
rm ~/.credentials/gmail-token.json

# Run newsletter check again
"Check newsletters"

# This triggers new OAuth flow
# Follow prompts in browser
# Grant Gmail access
# Should create new token

Fix: Verify Gmail Label Exists

# Check you have newsletters labeled

1. Open Gmail
2. Search for: label:8020brain
3. Should show labeled emails

If no results:

• Create "8020brain" label
• Apply to some newsletters manually
• Create filters to auto-label future emails

Create filter:

1. Search: from:newsletter@source.com
2. Click "Create filter"
3. Check "Apply label: 8020brain"
4. Check "Also apply to matching conversations"
5. Create

Fix: Verify Gmail API Enabled

1. Go to Google Cloud Console
2. Select your project
3. Go to "APIs & Services" → "Library"
4. Search "Gmail API"
5. Verify it shows "Manage" (means enabled)
6. If shows "Enable", click to enable it

Common Causes Summary

• Credentials missing → Create and download from Google Cloud
• Token expired → Delete token, re-auth
• No labeled emails → Create label, apply to emails
• API not enabled → Enable Gmail API in Cloud Console
• Wrong scope → Delete token, re-auth with full scope
• Rate limit hit → Wait 1 hour, try again

Issue 3: Brain Advisor Returns Nothing

Symptoms

• Query runs but returns "No relevant information found"
• Empty results
• "I don't have information about that"
• Agent completes but no insights

Fix: Check You Have Research

# List newsletter files
ls -la research/newsletters/

# List YouTube transcripts
ls -la research/youtube/

# Check index files exist
ls -la context/ideas/

If empty or very few files:

Your brain needs feeding!

• See Feeding Your Brain
• Run newsletter check: "Check newsletters"
• Fetch some videos: /fetch [youtube-url]
• Give it time to build up content

Reality check: With only 2-3 newsletters captured, results will be limited. Brain works better with 20+ sources indexed.

Fix: Check Query Specificity

Your query might be too vague or use different keywords:

❌ Too vague:

"Tell me about AI"

✅ Better:

"What have I learned about AI implementation strategies from Ethan Mollick and Ben Thompson?"

Tips:

• Be specific about topic
• Mention source names when you remember them
• Use keywords likely to appear in your research
• Frame as a question, not a statement

Fix: Verify brain-advisor Agent

# Check agent file exists
ls .claude/agents/brain-advisor/

# Should show agent.md file

If missing:

The brain-advisor agent is part of the brain template. If it's missing, you may need to:

1. Pull latest from repo: git pull
2. Or restore from backup
3. Or ask in Circle for the agent file

Fix: Try Explicit Invocation

Sometimes natural language doesn't trigger properly:

# Instead of: "What do I know about X?"
# Try explicit:
"Use brain-advisor agent to search for information about X"

Forces the agent to run.

Common Causes Summary

• Empty brain → Feed it more research
• Query too vague → Be more specific
• Keywords don't match → Try different terms
• Agent not triggering → Use explicit invocation
• Research exists but not indexed → Verify index files in context/ideas/

Issue 4: MCP Server Errors

Symptoms

• "MCP server not responding"
• "Failed to connect to [server]"
• "Timeout waiting for MCP response"
• Tool calls fail silently

Fix: Check MCP Config Exists

# Verify MCP settings file
cat ~/.claude/mcp_settings.json

# Should show JSON config with servers listed

If missing or empty:

MCP servers need configuration. Example config:

{
  "mcpServers": {
    "google-ads": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/google_ads_mcp",
        "run",
        "google-ads-mcp"
      ],
      "timeout": 30000
    }
  }
}

Fix: Check Server Is Installed

# Navigate to server directory
cd /path/to/mcp/server

# Verify it exists
ls

# Try running server manually
uv run server-name

If server missing:

Install the MCP server:

• Follow server's installation instructions
• Clone repo if needed
• Install dependencies
• Add to mcp_settings.json

Fix: Increase Timeout

Large queries or slow connections may timeout:

Edit ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "your-server": {
      "timeout": 60000  // Increase from 30000 to 60000 (60 seconds)
    }
  }
}

Fix: Check Logs

MCP servers write logs:

# Check Claude Code logs
tail -f ~/.claude/logs/mcp-*.log

# Look for error messages
# Common issues:
# - Import errors (missing dependencies)
# - Auth errors (credentials invalid)
# - Connection errors (network issues)

Fix: Restart Claude Code

Sometimes MCP servers get stuck:

1. Quit Claude Code completely
2. Wait 5 seconds
3. Restart Claude Code
4. Try MCP call again

Common Causes Summary

• Server not configured → Add to mcp_settings.json
• Server not installed → Install and configure
• Timeout too short → Increase in config
• Server crashed → Check logs, restart
• Credentials invalid → Update server config
• Dependencies missing → Reinstall server

Issue 5: Skills Not Auto-Activating

Symptoms

• Skill should trigger but doesn't
• Have to manually invoke skill
• Claude doesn't recognize trigger words
• Skill exists but never activates

Fix: Check Skill File

# Verify skill exists
ls .claude/skills/skill-name/

# Read skill definition
cat .claude/skills/skill-name/skill.md

Check:

• File exists and is readable
• Has clear trigger conditions
• Markdown syntax is valid
• No typos in activation description

Fix: Use Explicit Trigger Words

Skills activate based on patterns. Check the skill's trigger words and use them exactly:

Example: google-ads-data skill

Triggers:

• Mentions of Google Ads metrics
• Account names (MPM, SSC, etc.)
• Data requests ("get", "show me", "pull")

Test:

"Get search terms for MPM last 30 days"
# Should auto-activate google-ads-data skill

Use exact keywords from skill description.

Fix: Check for Conflicts

Multiple skills with similar triggers can conflict:

# List all skills
ls .claude/skills/

# Check each for similar triggers

If conflict:

• Rename triggers to be more specific
• Disable one skill temporarily
• Merge conflicting skills

Fix: Manual Invocation

Force skill to run:

# Use Skill tool
command: "skill-name"

If this works but auto-activation doesn't, trigger words need refinement.

Common Causes Summary

• Trigger words too vague → Be more specific in skill definition
• Didn't use trigger words → Use exact keywords
• Skill file syntax error → Check markdown validity
• Competing skills → Resolve conflicts
• Context doesn't match → Skill activates only in certain contexts

Issue 6: Queries Are Slow

Symptoms

• Long wait times (30+ seconds)
• Timeouts on complex queries
• First query takes forever
• Incomplete results

Expected Performance

First query per session:

• 30-60 seconds (indexes all research)
• Building searchable index
• Normal and expected

Subsequent queries:

• 5-15 seconds (uses cache)
• Searches existing index
• Much faster

Complex synthesis:

• 10-20 seconds
• Multiple sources
• Heavy AI processing
• Worth the wait

If slower than this, investigate:

Fix: Large Research Archive

# Check research size
du -sh research/

# If over 1GB, consider optimization

Solutions:

• Archive old content you don't reference
• Move to archive/ folder outside brain
• Keep only actively used sources
• Quality over quantity

Archive old research:

# Create archive
mkdir -p ~/archive/brain-research

# Move old content
mv research/newsletters/source-2023 ~/archive/brain-research/

# Keeps brain lean

Fix: Too Many Sources

More sources = slower searches:

# Count sources
ls research/newsletters/ | wc -l
ls research/youtube/ | wc -l

If 20+ sources:

Consider focusing:

• Keep 5-10 core sources active
• Archive less-used sources
• Remove sources you never query

Remember: 5 great sources beat 50 mediocre ones.

Fix: Increase Timeout

If queries timeout before completing:

For MCP servers, edit ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "server-name": {
      "timeout": 90000  // 90 seconds
    }
  }
}

For agent tasks, they have their own timeout settings (usually sufficient).

Not Actually a Problem

Sometimes "slow" is just thorough:

• Searching 100+ documents
• Synthesizing multiple perspectives
• Complex AI reasoning
• Generating comprehensive response

This is working as designed.

Grab coffee. The wait is worth it for quality synthesis.

Issue 7: Git/Sync Problems

Symptoms

• Can't pull latest changes
• Conflicts on files
• "Your branch has diverged"
• Lost local changes

Fix: Config File Conflicts

CLAUDE.md files often conflict (you customized, repo updated):

# Keep your local version
git checkout --ours ~/.claude/CLAUDE.md
git add ~/.claude/CLAUDE.md

# Or keep repo version
git checkout --theirs ~/.claude/CLAUDE.md
git add ~/.claude/CLAUDE.md

# Then finish merge
git commit -m "Resolve config conflict"

Pro tip: Keep customizations in global config (~/.claude/CLAUDE.md), not brain config. Makes updates easier.

Fix: Research Conflicts

Usually want latest research from repo:

# Accept repo version
git checkout --theirs research/
git add research/
git commit -m "Accept latest research"

Your local research should be in additions, not conflicts.

Fix: Start Fresh (Nuclear Option)

When git is too tangled:

# From within your brain folder, backup your customizations
cp CLAUDE.md ~/CLAUDE-backup.md
cp ~/.claude/CLAUDE.md ~/.claude/CLAUDE-backup.md

# Backup any custom agents/skills
cp -r .claude/agents ~/custom-agents-backup
cp -r .claude/skills ~/custom-skills-backup

# Move up and remove brain folder
cd ..
rm -rf [your-brain-folder-name]

# Re-clone fresh
git clone [repo-url] [your-brain-folder-name]
cd [your-brain-folder-name]

# Restore customizations
cp ~/CLAUDE-backup.md CLAUDE.md
cp ~/.claude/CLAUDE-backup.md ~/.claude/CLAUDE.md
# Restore custom agents/skills as needed

Clean slate. Sometimes necessary.

Fix: Prevent Future Conflicts

Best practices:

1. Customize in right place:

   • Personal preferences → ~/.claude/CLAUDE.md
   • Brain-specific → CLAUDE.md in your brain folder
   • Custom agents/skills → Keep backed up

2. Pull before editing:

   git pull
   # Then make changes
   

3. Commit regularly:

   git add .
   git commit -m "My changes"
   git pull  # Deals with conflicts when small
   

4. Use branches for experiments:

   git checkout -b my-experiment
   # Try things
   # If good, merge. If bad, delete branch.
   

The "I'm Completely Stuck" Checklist

Tried everything above? Go through this checklist in order:

1. Restart Everything

• Quit Claude Code completely
• Wait 10 seconds
• Restart Claude Code
• Try again

Fixes 40% of issues.

2. Verify Basics

• You're in the right directory (pwd shows brain folder)
• Latest changes pulled (git pull)
• Credentials exist (Gmail, API keys)
• Research exists (ls research/)

3. Test Simple Query

# Try something basic
"What folders exist in my brain?"

# Should list folders

If this fails, something fundamental is broken.

4. Check Versions

# Claude Code version
claude --version

# Git version
git --version

# Node version (if applicable)
node --version

Update if very old versions.

5. Review Recent Changes

What changed since it last worked?

• Installed something?
• Updated something?
• Changed config?
• Moved files?

Undo recent changes and test.

6. Check Logs

# Claude Code logs (if accessible)
tail -f ~/.claude/logs/*.log

# Look for errors

Error messages point to root cause.

7. Ask Circle

If still stuck, post in Circle with:

What you tried:

• List troubleshooting steps from above
• What worked, what didn't

Error messages:

• Exact text of errors
• Screenshots if visual

Environment:

• OS: [Mac/Windows/Linux]
• Claude Code version: [from claude --version]
• What command you ran

Example:

I'm trying to fetch newsletters but getting "Authentication error".

Tried:
- Verified google-credentials.json exists
- Deleted token and re-authed
- Gmail API is enabled
- Labeled emails exist

Still fails with: [exact error]

Environment:
- macOS 14.0
- Claude Code 1.2.3
- Command: "Check newsletters"

Screenshots: [attach]

Someone has hit this. Community will help.

General Troubleshooting Tips

Read Error Messages

Actually read them. They usually say what's wrong:

• "File not found" → File missing or wrong path
• "Permission denied" → File permissions issue
• "Authentication failed" → Credentials invalid
• "Timeout" → Operation took too long

Fix what the error says is broken.

Test in Isolation

Narrow down the problem:

• Does Claude Code work at all?
• Does git work?
• Does the specific MCP server work?
• Does a simple query work?

Find the smallest thing that fails. Fix that first.

Check the Obvious

Before diving deep:

• Did you spell it correctly?
• Are you in the right folder?
• Did you save the file?
• Did you restart after installing?

Obvious fixes resolve 50% of issues.

Make One Change at a Time

When troubleshooting:

1. Try one fix
2. Test if it worked
3. If not, try next fix
4. Don't pile up changes

Otherwise you don't know what fixed it.

Document Solutions

When you fix something:

# Add to your notes
echo "Problem: [what broke]
Solution: [how you fixed it]
Date: $(date)" >> ~/brain-troubleshooting-notes.md

Help future you and others.

Remember: It's Early Days

This is power user software. Rough edges are expected.

Your troubleshooting and feedback makes it better for everyone.

Every issue documented is one less person stuck later.

Next: Ready for power user territory? →

Quick Reference

Most common issues:

1. Command not found → Install/check PATH
2. Gmail fetch fails → Check credentials, re-auth
3. No results from brain → Need more research
4. MCP errors → Check config, restart
5. Skills don't activate → Use trigger words
6. Slow queries → Normal for first run
7. Git conflicts → Keep local config, repo research

Stuck checklist:

1. Restart Claude Code
2. Verify basics (directory, credentials)
3. Test simple query
4. Check versions
5. Review recent changes
6. Check logs
7. Ask Circle

Prevention:

• Pull before editing
• Commit regularly
• Customize in right place
• Keep backups
• Document solutions

Get help:

• Post in Circle
• Include error messages
• List what you tried
• Share environment details