adaptationio/auto-claude-troubleshooting

Auto-Claude Troubleshooting

Comprehensive debugging guide for all Auto-Claude issues.

Quick Diagnostics

Check System Requirements

# Python version (need 3.12+)
python3 --version

# Node.js version (need 24+)
node --version

# Claude Code CLI
claude --version

# Git
git --version

Verify Installation

cd apps/backend

# Check virtual environment
source .venv/bin/activate  # or .venv\Scripts\activate
python --version

# Test import
python -c "from core.client import create_client; print('OK')"

# Check dependencies
pip list | grep claude-agent-sdk

Check Configuration

# Environment variables
cat .env | grep -v "^#" | grep -v "^$"

# OAuth token
echo $CLAUDE_CODE_OAUTH_TOKEN | head -c 20

# Test Claude Code
claude --version

Common Issues

Installation Problems

Python Version Mismatch

# Wrong Python version
$ python3 --version
Python 3.9.7  # Too old!

# Fix: Install Python 3.12+
# macOS
brew install [email protected]

# Ubuntu
sudo apt install python3.12 python3.12-venv

# Windows
winget install Python.Python.3.12

# Create venv with correct version
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

node-gyp Errors (Windows)

# Error: node-gyp rebuild failed

# Fix: Install Visual Studio Build Tools
# 1. Download from https://visualstudio.microsoft.com/visual-cpp-build-tools/
# 2. Select "Desktop development with C++"
# 3. Restart terminal
npm install

Permission Denied

# Error: Permission denied

# Fix: Use sudo or change ownership
sudo npm install -g @anthropic-ai/claude-code

# Or fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Authentication Issues

OAuth Token Invalid

# Error: Invalid OAuth token

# Fix: Re-generate token
claude setup-token

# Add to .env
echo "CLAUDE_CODE_OAUTH_TOKEN=$(claude setup-token --output)" >> apps/backend/.env

Token Not Found

# Error: CLAUDE_CODE_OAUTH_TOKEN not set

# Check if set
echo $CLAUDE_CODE_OAUTH_TOKEN

# Set manually
export CLAUDE_CODE_OAUTH_TOKEN="your-token-here"

# Or add to .env
echo "CLAUDE_CODE_OAUTH_TOKEN=your-token-here" >> apps/backend/.env

Subscription Issues

# Error: Claude Pro/Max subscription required

# Fix: Verify subscription at https://claude.ai/upgrade
# Must have active Pro or Max subscription

Build Failures

Spec Not Found

# Error: Spec 001 not found

# List available specs
python run.py --list

# Check spec directory
ls -la .auto-claude/specs/

# Create spec first
python spec_runner.py --interactive

Agent Timeout

# Error: Agent timed out

# Increase timeout
API_TIMEOUT_MS=600000 python run.py --spec 001

# Or add to .env
echo "API_TIMEOUT_MS=600000" >> .env

Build Stuck

# Build appears stuck

# Check progress
tail -f .auto-claude/specs/001-feature/build-progress.txt

# Check for PAUSE file
ls -la .auto-claude/specs/001-feature/PAUSE

# Remove pause
rm .auto-claude/specs/001-feature/PAUSE

# Add human input to unstick
echo "Please proceed with the next subtask" > .auto-claude/specs/001-feature/HUMAN_INPUT.md

Security Hook Rejection

# Error: Command not allowed

# Check security log
cat .auto-claude-security.json

# Add command to allowlist in security.py
# Or run without sandbox (not recommended)

Workspace Issues

Worktree Already Exists

# Error: Worktree already exists

# Remove existing worktree
git worktree remove .worktrees/auto-claude/001-feature

# Or force remove
git worktree remove --force .worktrees/auto-claude/001-feature
git worktree prune

Branch Already Exists

# Error: Branch auto-claude/001-feature already exists

# Delete existing branch
git branch -D auto-claude/001-feature

# Then retry
python run.py --spec 001

Merge Conflicts

# Error: Merge conflicts detected

# Manual resolution
cd .worktrees/auto-claude/001-feature/
git merge main --no-commit
git status

# Resolve conflicts in editor
code path/to/conflicted/file

# Complete merge
git add .
git commit -m "Resolved conflicts"
cd ../../apps/backend

Memory System Issues

Graphiti Not Working

# Error: Graphiti initialization failed

# Check if enabled
grep GRAPHITI apps/backend/.env

# Verify provider credentials
# For OpenAI
curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models

# For Ollama
curl http://localhost:11434/api/tags

Embedding Dimension Mismatch

# Error: Embedding dimension mismatch

# Clear embeddings and re-index
rm -rf ~/.auto-claude/memories/embeddings
python run.py --spec 001

Database Corruption

# Error: Database corrupted

# Backup and reset
mv ~/.auto-claude/memories ~/.auto-claude/memories.backup
python query_memory.py --search "test"  # Creates fresh DB

QA Issues

QA Loop Never Completes

# QA keeps rejecting

# Check QA report
cat .auto-claude/specs/001-feature/qa_report.md

# Skip QA temporarily
python run.py --spec 001 --skip-qa

# Or limit iterations
MAX_QA_ITERATIONS=5 python run.py --spec 001 --qa

QA Fixer Not Fixing

# QA Fixer fails to fix issues

# Check fix request
cat .auto-claude/specs/001-feature/QA_FIX_REQUEST.md

# Add human guidance
echo "Focus on fixing the session storage issue first" > .auto-claude/specs/001-feature/HUMAN_INPUT.md

Debug Mode

Enable Verbose Logging

# Level 1: Basic
DEBUG=true DEBUG_LEVEL=1 python run.py --spec 001

# Level 2: Detailed
DEBUG=true DEBUG_LEVEL=2 python run.py --spec 001

# Level 3: Verbose (everything)
DEBUG=true DEBUG_LEVEL=3 python run.py --spec 001

Log to File

# Log to file
DEBUG=true DEBUG_LOG_FILE=debug.log python run.py --spec 001

# View in real-time
tail -f debug.log

Agent Communication

# See agent messages
DEBUG=true python run.py --spec 001 2>&1 | tee agent.log

# Search for errors
grep -i error agent.log
grep -i failed agent.log

Recovery Procedures

Restart Clean

# Full reset for a spec
rm -rf .auto-claude/specs/001-feature
rm -rf .worktrees/auto-claude/001-feature
git branch -D auto-claude/001-feature 2>/dev/null
git worktree prune

# Recreate spec
python spec_runner.py --task "Your task description"

Resume from Checkpoint

# Continue interrupted spec
python spec_runner.py --continue 001-feature

# Continue interrupted build
python run.py --spec 001

Manual Intervention

# 1. Pause the build
touch .auto-claude/specs/001-feature/PAUSE

# 2. Make manual changes in worktree
cd .worktrees/auto-claude/001-feature/
# ... edit files ...
git add .
git commit -m "Manual fix"

# 3. Resume
cd ../../apps/backend
rm .auto-claude/specs/001-feature/PAUSE
python run.py --spec 001

Performance Issues

Slow Builds

# Use faster model
AUTO_BUILD_MODEL=claude-sonnet-4-5-20250929 python run.py --spec 001

# Reduce thinking tokens
# Edit agent creation to use max_thinking_tokens=3000

# Skip research phase
SKIP_RESEARCH_PHASE=true python spec_runner.py --task "..."

High Memory Usage

# Monitor memory
watch -n 1 'ps aux | grep python'

# Reduce context
MAX_CONTEXT_FILES=30 python run.py --spec 001

# Use smaller embedding model
OLLAMA_EMBEDDING_MODEL=all-minilm
OLLAMA_EMBEDDING_DIM=384

API Rate Limits

# Error: Rate limit exceeded

# Wait and retry
sleep 60
python run.py --spec 001

# Or use different endpoint
ANTHROPIC_BASE_URL=http://localhost:3456 python run.py --spec 001

Getting Help

Gather Diagnostics

# System info
echo "Python: $(python3 --version)"
echo "Node: $(node --version)"
echo "Git: $(git --version)"
echo "Claude: $(claude --version)"

# Auto-Claude version
cat package.json | grep '"version"'

# Last 50 lines of logs
tail -50 .auto-claude/specs/*/build-progress.txt

Community Resources

• Discord: https://discord.gg/KCXaPBr4Dj
• GitHub Issues: https://github.com/AndyMik90/Auto-Claude/issues
• Discussions: https://github.com/AndyMik90/Auto-Claude/discussions

Report a Bug

Include:

1. Operating system and version
2. Python and Node.js versions
3. Auto-Claude version
4. Steps to reproduce
5. Error messages
6. Relevant logs

Related Skills

• auto-claude-setup: Installation guide
• auto-claude-cli: CLI reference
• auto-claude-optimization: Performance tuning