Troubleshooting Guide

December 19, 2025 · View on GitHub

Common issues and solutions for Sugar users.

🚨 Common Issues

Claude CLI Not Found

Problem: Sugar reports "Claude CLI not found" during initialization.

Solutions:

Install Claude CLI:

npm install -g @anthropic-ai/claude-code-cli
claude --version  # Verify installation

Check PATH:

which claude  # Should return path to claude
echo $PATH    # Verify PATH includes claude location

Manual Configuration: Edit .sugar/config.yaml:

sugar:
  claude:
    command: "/full/path/to/claude"  # Specify exact path

Common Claude CLI Locations:

/usr/local/bin/claude
/opt/homebrew/bin/claude (macOS with Homebrew)
~/.local/bin/claude
~/.claude/local/claude

No Work Discovered

Problem: Sugar doesn't find any tasks to work on.

Solutions:

Check Discovery Paths:

# Verify error log directories exist
ls -la logs/errors/

# Create if missing
mkdir -p logs/errors/

Test with Sample Error:

echo '{"error": "test", "message": "sample error"}' > logs/errors/test.json
sugar run --dry-run --once

Enable Discovery Sources: Edit .sugar/config.yaml:

sugar:
  discovery:
    error_logs:
      enabled: true
      paths: ["logs/errors/", "logs/feedback/"]
    code_quality:
      enabled: true
    test_coverage:
      enabled: true

Validate Configuration:
```
sugar run --validate
```

Tasks Not Executing

Problem: Tasks remain pending and never execute.

Solutions:

Check Dry Run Mode: Edit .sugar/config.yaml:

sugar:
  dry_run: false  # Must be false for real execution

Check Claude CLI Access:

claude --version  # Should work without error

Monitor Logs:
```
tail -f .sugar/sugar.log
```

Test Single Task:

sugar add "test task" --type feature
sugar run --once --dry-run  # Test in safe mode first

Permission Errors

Problem: Sugar can't write to directories or access files.

Solutions:

Check File Permissions:

ls -la .sugar/
chmod 755 .sugar/
chmod 644 .sugar/config.yaml

Check Directory Ownership:

ls -la | grep .sugar
# Should be owned by your user

Verify Write Access:

touch .sugar/test_file
rm .sugar/test_file

Database Errors

Problem: SQLite database errors or corruption.

Solutions:

Check Database File:

ls -la .sugar/sugar.db
file .sugar/sugar.db  # Should show "SQLite 3.x database"

Reset Database:

# Backup first
cp .sugar/sugar.db .sugar/sugar.db.backup

# Remove and reinitialize
rm .sugar/sugar.db
sugar status  # Will recreate database

Check Disk Space:

df -h .  # Ensure sufficient disk space

High Memory/CPU Usage

Problem: Sugar consumes too many resources.

Solutions:

Reduce Concurrency: Edit .sugar/config.yaml:

sugar:
  max_concurrent_work: 1  # Reduce from default 3

Increase Loop Interval:

sugar:
  loop_interval: 600  # 10 minutes instead of 5

Limit File Scanning:

sugar:
  discovery:
    code_quality:
      max_files_per_scan: 25  # Reduce from 50

Monitor Resource Usage:
```
top -p $(pgrep -f sugar)
```

Running Sugar Inside Claude Code

Problem: User tries to run Sugar from within a Claude Code session.

Issue: This creates a recursive execution pattern that can cause:

Context confusion between Sugar and Claude Code states
Authentication conflicts
Resource conflicts with file management
Nested Claude CLI calls

Solution: Sugar should be run outside of Claude Code sessions:

Exit Claude Code if you're currently in a session
Open a regular terminal/shell in your project directory

Run Sugar directly:

# Correct: Run in regular terminal
cd /path/to/your/project
sugar init
sugar run

Let Sugar call Claude Code as needed for task execution

Architecture:

✅ Correct: Terminal → Sugar → Claude Code CLI (for tasks)
❌ Incorrect: Claude Code → Sugar → Claude Code CLI (recursive)

Verification: Check that you're in a regular terminal (not Claude Code) by running:

echo $CLAUDE_SESSION  # Should be empty
which sugar          # Should show Sugar path

🔍 Diagnostic Commands

Check Sugar Status

sugar status  # System overview
sugar list    # Task queue

Validate Configuration

sugar run --validate  # Check all settings

Test Discovery

sugar run --dry-run --once  # Safe test run

Check Logs

# Sugar logs
tail -f .sugar/sugar.log

# System logs (macOS)
log show --predicate 'process == "sugar"' --last 1h

# System logs (Linux)
journalctl -f -u sugar

Database Inspection

# Install sqlite3 if needed
sqlite3 .sugar/sugar.db

# In SQLite prompt:
.tables                    # List tables
.schema work_items         # Show table structure
SELECT * FROM work_items;  # Show all tasks
.quit                      # Exit

📊 Performance Optimization

For Large Projects

sugar:
  discovery:
    code_quality:
      max_files_per_scan: 25
      excluded_dirs: [
        "node_modules", "venv", "dist", "build", 
        "coverage", "docs", "examples", ".git"
      ]

For Many Log Files

sugar:
  discovery:
    error_logs:
      max_age_hours: 12    # Only recent errors
      patterns: ["*.json"] # Limit to structured logs

For Slow Systems

sugar:
  loop_interval: 900       # 15 minutes between cycles
  max_concurrent_work: 1   # Single task at a time
  
  claude:
    timeout: 3600          # Allow longer execution time

🛡️ Safety Checks

Sugar has built-in safety measures:

Dry run by default - No changes until you set dry_run: false
Path exclusions - Won't modify system directories
Timeout protection - Tasks have maximum execution time
Retry limits - Failed tasks won't retry infinitely

Emergency Stop

# Stop running Sugar
pkill -f "sugar run"

# Or use Ctrl+C in the terminal running Sugar

🆘 Getting Help

If you can't resolve the issue:

Search Issues: Check GitHub Issues
Create Issue: Include:
- Sugar version (sugar --version)
- Operating system
- Python version
- Claude CLI version
- Configuration file (remove sensitive data)
- Log files
- Steps to reproduce
Emergency Contact: contact@roboticforce.io

🔧 Debug Mode

Enable detailed logging:

export SUGAR_LOG_LEVEL=DEBUG
sugar run --dry-run --once

Or edit .sugar/config.yaml:

sugar:
  logging:
    level: "DEBUG"