Troubleshooting

Troubleshooting Guide

This guide covers common issues and their solutions when using Claude Autopilot.

Quick Diagnostic Checklist

Before diving into specific issues, run through this quick checklist:

1. ✅ VS Code Version: Ensure you're running VS Code 1.74.0 or later
2. ✅ Claude Autopilot Version: Check you have the latest version installed
3. ✅ Dependencies: Verify Claude Code and Python are installed and accessible
4. ✅ Permissions: Check if Claude Autopilot has necessary permissions
5. ✅ Configuration: Review your Claude Autopilot settings for any invalid values

Common Issues

1. "Claude not found" Error

Symptoms:

• Error message: "Claude CLI not found in PATH"
• Dependency check fails
• Cannot start Claude session

Solutions:

Check Claude Installation

# Test if Claude is accessible
claude --version

# If not found, check your PATH
echo $PATH  # macOS/Linux
echo $env:PATH  # Windows PowerShell

Fix PATH Issues

macOS/Linux:

# Add to ~/.bashrc, ~/.zshrc, or ~/.profile
export PATH="/path/to/claude:$PATH"

# Reload shell configuration
source ~/.bashrc  # or ~/.zshrc

Windows:

1. Open System Properties → Advanced → Environment Variables
2. Edit PATH variable
3. Add Claude installation directory
4. Restart VS Code and terminal

Reinstall Claude Code

1. Uninstall current Claude Code installation
2. Download latest version from official source
3. Restart VS Code after installation

2. "Python not found" Error

Symptoms:

• Error message: "Python not found"
• PTY wrapper fails to start
• Session initialization errors

Solutions:

Verify Python Installation

# Check Python availability
python --version
python3 --version

# Check which Python Claude Autopilot is trying to use
which python   # macOS/Linux
where python   # Windows

Fix Python PATH

macOS:

# If using Homebrew Python
export PATH="/opt/homebrew/bin:$PATH"

# If using system Python
export PATH="/usr/bin:$PATH"

Windows:

1. Reinstall Python with "Add Python to PATH" checked
2. Or manually add Python to PATH in System Properties
3. Restart VS Code

Linux:

# Install Python if missing
sudo apt install python3 python3-pip  # Ubuntu/Debian
sudo dnf install python3 python3-pip  # Fedora

3. Permission Denied Errors

Symptoms:

• "Permission denied" when starting Claude
• Cannot create queue files
• Workspace access issues

Solutions:

Enable Skip Permissions

{
  "claudeAutopilot.session.skipPermissions": true
}

Fix File Permissions

macOS/Linux:

# Fix workspace permissions
chmod -R 755 /path/to/your/workspace

# Fix Claude Autopilot data directory
chmod -R 755 ~/.vscode/extensions/benbasha.claude-loop-*

Windows:

1. Run VS Code as Administrator (temporary solution)
2. Check folder permissions in Properties → Security
3. Ensure your user has full control

4. Queue Processing Stuck

Symptoms:

• Queue shows "Processing" but no progress
• Messages remain in "pending" state
• No output generated

Solutions:

Check Claude Process Health

1. Open Claude Autopilot panel
2. Check process status indicator
3. Look for error messages in output

Restart Claude Session

1. Stop Claude Autopilot: Claude: Stop Claude Autopilot
2. Wait 5 seconds
3. Start Claude Autopilot: Claude: Start Claude Autopilot

Clear Queue State

# Navigate to workspace
cd /path/to/your/workspace

# Remove queue state files
rm -rf .vscode/claudeloop-*

Check System Resources

• Monitor CPU and memory usage
• Ensure sufficient disk space
• Close unnecessary applications

5. Auto-Resume Not Working

Symptoms:

• Queue stops after hitting Claude limits
• No automatic resumption
• Manual restart required

Solutions:

Enable Auto-Resume Features

{
  "claudeAutopilot.session.autoStart": true,
  "claudeAutopilot.queue.autoMaintenance": true
}

Check Network Connectivity

# Test internet connection
ping google.com

# Test Claude API accessibility (if applicable)
curl -I https://api.anthropic.com

Review Usage Limits

1. Check your Claude usage dashboard
2. Verify limit reset times
3. Ensure you have remaining quota

6. High Memory Usage

Symptoms:

• VS Code becomes slow
• System memory consumption high
• Extension host crashes

Solutions:

Reduce Queue Size

{
  "claudeAutopilot.queue.maxSize": 100,
  "claudeAutopilot.queue.maxMessageSize": 25000,
  "claudeAutopilot.queue.maxOutputSize": 50000
}

Enable Auto Maintenance

{
  "claudeAutopilot.queue.autoMaintenance": true,
  "claudeAutopilot.queue.retentionHours": 6
}

Clear History

1. Open Claude Autopilot panel
2. Go to History tab
3. Clear old runs manually

7. Configuration Issues

Symptoms:

• Settings don't take effect
• Invalid configuration warnings
• Extension fails to load

Solutions:

Validate Configuration

1. Open VS Code Settings
2. Search for "Claude Autopilot"
3. Check for red error indicators

Reset Configuration

// Remove all Claude Autopilot settings from settings.json
// Let extension use defaults

Check JSON Syntax

Ensure your settings.json has valid JSON syntax:

{
  "claudeAutopilot.developmentMode": true,  // ✅ Valid
  "claudeAutopilot.queue.maxSize": 500      // ✅ No trailing comma
}

Platform-Specific Issues

macOS Issues

Gatekeeper Blocking Claude

# If Claude is blocked by Gatekeeper
sudo spctl --add /path/to/claude
sudo xattr -r -d com.apple.quarantine /path/to/claude

Python SSL Certificate Issues

# Update certificates
/Applications/Python\ 3.x/Install\ Certificates.command

Windows Issues

PowerShell Execution Policy

# Check current policy
Get-ExecutionPolicy

# Set policy if needed (run as Administrator)
Set-ExecutionPolicy RemoteSigned

Windows Defender Blocking

1. Add Claude and Python to Windows Defender exclusions
2. Add VS Code extensions folder to exclusions

Linux Issues

Missing System Dependencies

# Ubuntu/Debian
sudo apt install build-essential python3-dev

# Fedora
sudo dnf groupinstall "Development Tools"
sudo dnf install python3-devel

SELinux Context Issues

# Check SELinux status
sestatus

# Temporarily disable if needed
sudo setenforce 0

Advanced Troubleshooting

Enable Debug Logging

{
  "claudeAutopilot.developmentMode": true,
  "claudeAutopilot.logging.enabled": true,
  "claudeAutopilot.logging.level": "debug"
}

Check Extension Host Console

1. Open Command Palette (Cmd/Ctrl+Shift+P)
2. Run: Developer: Toggle Developer Tools
3. Go to Console tab
4. Look for Claude Autopilot-related errors

Analyze Log Files

macOS/Linux:

# VS Code logs
~/Library/Application\ Support/Code/logs/  # macOS
~/.config/Code/logs/  # Linux

# Extension logs (if logging enabled)
find ~/.vscode/extensions -name "*claude-loop*" -type d

Windows:

# VS Code logs
%APPDATA%\Code\logs\

# Extension directory
%USERPROFILE%\.vscode\extensions\

Clean Reinstall

1. Uninstall Extension:

   code --uninstall-extension benbasha.claude-loop

2. Clear Extension Data:

   # Remove extension data
   rm -rf ~/.vscode/extensions/benbasha.claude-loop-*
   
   # Clear workspace data
   find . -name ".vscode" -type d -exec rm -rf {}/claudeloop-* \;

3. Reinstall Extension:

   code --install-extension benbasha.claude-loop

Performance Issues

Slow Queue Processing

Causes:

• Large message sizes
• Complex processing tasks
• System resource constraints

Solutions:

1. Break large messages into smaller chunks
2. Increase health check interval
3. Close unnecessary applications
4. Upgrade system resources if possible

VS Code Freezing

Immediate Actions:

1. Kill VS Code process
2. Restart VS Code
3. Disable Claude Autopilot temporarily

Long-term Solutions:

1. Reduce queue size limits
2. Enable auto-maintenance
3. Monitor system resources
4. Update VS Code and Claude Autopilot

Error Code Reference

Error Code	Description	Solution
CLAUDE_NOT_FOUND	Claude CLI not in PATH	Install Claude, fix PATH
PYTHON_NOT_FOUND	Python not accessible	Install Python, fix PATH
PERMISSION_DENIED	Insufficient permissions	Enable skip permissions
QUEUE_FULL	Queue size limit reached	Increase maxSize or enable auto-maintenance
SESSION_FAILED	Claude session failed	Restart session, check dependencies
PROCESS_TIMEOUT	Operation timed out	Check system resources, increase timeouts

Getting Help

Before Asking for Help

1. Review this troubleshooting guide
2. Check Known Issues
3. Search GitHub Issues
4. Enable debug logging and collect logs

When Reporting Issues

Include the following information:

System Information:

• OS and version
• VS Code version
• Claude Autopilot version
• Claude Code version
• Python version

Error Details:

• Exact error message
• Steps to reproduce
• Expected vs actual behavior
• Screenshots or logs

Configuration:

• Relevant Claude Autopilot settings
• Workspace configuration
• Environment variables

Support Channels

1. GitHub Issues - Bug reports and feature requests
2. GitHub Discussions - Questions and community support
3. FAQ - Common questions and answers

Emergency Recovery

Complete Reset

If Claude Autopilot is completely broken:

1. Stop all Claude Autopilot processes:

   # Kill any hanging processes
   pkill -f claude
   pkill -f python.*claude

2. Remove all data:

   # Remove extension data
   rm -rf ~/.vscode/extensions/benbasha.claude-loop-*
   
   # Remove workspace data
   find . -name ".vscode" -type d -exec rm -rf {}/claudeloop-* \;

3. Reset VS Code:

   # Close VS Code
   # Clear VS Code cache (optional)
   rm -rf ~/.vscode/extensions/extensions.json

4. Reinstall:

   code --install-extension benbasha.claude-loop

---

Troubleshooting guide last updated: July 2025