SuperClaude/Framework-Hooks/docs/TROUBLESHOOTING.md

Troubleshooting Guide

Common issues and solutions for Framework-Hooks based on actual implementation patterns.

Installation Issues

Python Import Errors

Problem: Hook fails with ModuleNotFoundError for shared modules

Cause: Python path not finding shared modules in hooks/shared/

Solution:

# Each hook script includes this path setup:
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "shared"))

Verify the shared/ directory exists and contains all 9 modules:

• framework_logic.py
• compression_engine.py
• learning_engine.py
• mcp_intelligence.py
• pattern_detection.py
• intelligence_engine.py
• logger.py
• yaml_loader.py
• validate_system.py

Hook Execution Permissions

Problem: Hooks fail to execute with permission errors

Solution:

cd Framework-Hooks/hooks
chmod +x *.py
chmod +x shared/*.py

The following hooks need execute permissions:

• pre_compact.py
• stop.py
• subagent_stop.py

YAML Configuration Errors

Problem: Hook fails with YAML parsing errors

Cause: Invalid YAML syntax in config files

Solution:

# Test YAML validity
python3 -c "import yaml; yaml.safe_load(open('config/session.yaml'))"

Check these configuration files for syntax issues:

• config/logging.yaml
• config/session.yaml
• config/performance.yaml
• config/compression.yaml
• All other .yaml files in config/

Performance Issues

Hook Timeout Errors

Problem: Hooks timing out (default 10-15 seconds from settings.json)

Cause: Performance targets not met:

• session_start.py: >50ms target
• pre_tool_use.py: >200ms target
• Other hooks: >100-150ms targets

Diagnosis:

# Enable timing logs in config/logging.yaml
logging:
  enabled: true
  level: "INFO"
  hook_logging:
    log_timing: true

Solutions:

1. Reduce pattern loading: Remove unnecessary patterns from patterns/ directories
2. Check disk I/O: Ensure cache/ directory is writable and has space
3. Disable verbose features: Set logging.level: "ERROR"
4. Check Python performance: Use faster Python interpreter if available

Memory Usage Issues

Problem: High memory usage during hook execution

Cause: Large pattern files or cache accumulation

Solutions:

1. Clear cache: Remove files from cache/ directory
2. Reduce pattern size: Check for oversized files in patterns/learned/
3. Limit learning data: Review learning_engine.py cache size limits

Pattern Loading Slow

Problem: Session start delays due to pattern loading

Cause: Pattern system loading large files from:

• patterns/minimal/: Should be 3-5KB each
• patterns/dynamic/: Should be 8-12KB each
• patterns/learned/: Should be 10-20KB each

Solutions:

1. Check pattern sizes: Identify oversized pattern files
2. Remove unused patterns: Delete patterns not relevant to your projects
3. Reset learned patterns: Clear patterns/learned/ to start fresh

Configuration Issues

Logging Not Working

Problem: No log output despite enabling logging

Cause: Default logging configuration in config/logging.yaml:

logging:
  enabled: false  # Default is disabled
  level: "ERROR"  # Only shows errors by default

Solution: Enable logging properly:

logging:
  enabled: true
  level: "INFO"    # or "DEBUG" for verbose output
  hook_logging:
    log_lifecycle: true
    log_decisions: true
    log_timing: true

Cache Directory Issues

Problem: Hooks fail with cache write errors

Cause: Missing or permission issues with cache/ directory

Solution:

mkdir -p Framework-Hooks/cache/logs
chmod 755 Framework-Hooks/cache
chmod 755 Framework-Hooks/cache/logs

Required cache structure:

cache/
├── logs/          # Log files (30-day retention)
├── patterns/      # Cached pattern data
├── learning/      # Learning engine data
└── session/       # Session state

MCP Intelligence Failures

Problem: MCP server coordination not working

Cause: mcp_intelligence.py configuration issues

Diagnosis: Check config/mcp_orchestration.yaml for valid server configurations

Solution: Verify MCP server availability and configuration in:

• Context7, Sequential, Magic, Playwright, Morphllm, Serena

Runtime Issues

Hook Script Failures

Problem: Individual hook scripts crash or fail

Diagnosis Steps:

1. Test hook directly:

cd Framework-Hooks/hooks
python3 session_start.py

2. Check imports: Verify all shared modules import correctly:

from framework_logic import FrameworkLogic
from pattern_detection import PatternDetector  
from mcp_intelligence import MCPIntelligence
from compression_engine import CompressionEngine
from learning_engine import LearningEngine

3. Check YAML loading:

from yaml_loader import config_loader
config = config_loader.load_config('session')

Learning System Issues

Problem: Learning engine not adapting to usage patterns

Cause: Learning data not persisting or invalid

Solutions:

1. Check cache permissions: Ensure cache/learning/ is writable
2. Reset learning data: Remove cache/learning/* files to start fresh
3. Verify pattern detection: Check that pattern_detection.py identifies your project type

Validation Failures

Problem: System validation reports errors

Run validation manually:

cd Framework-Hooks/hooks/shared
python3 validate_system.py --full-check

Common validation issues:

• Missing configuration files
• Invalid YAML syntax
• Permission problems
• Missing directories

Debug Mode

Enable Comprehensive Debugging

Edit config/logging.yaml:

logging:
  enabled: true
  level: "DEBUG"
  
development:
  verbose_errors: true
  include_stack_traces: true
  debug_mode: true

This provides detailed information about:

• Hook execution flow
• Pattern loading decisions
• MCP server coordination
• Learning system adaptations
• Performance timing data

Manual Hook Testing

Test individual hooks outside Claude Code:

# Test session start
python3 hooks/session_start.py

# Test tool use hooks  
python3 hooks/pre_tool_use.py
python3 hooks/post_tool_use.py

# Test cleanup hooks
python3 hooks/stop.py

System Health Checks

Automated Validation

Run the comprehensive system check:

cd Framework-Hooks/hooks/shared  
python3 validate_system.py --health-check

This checks:

• File permissions and structure
• YAML configuration validity
• Python module imports
• Cache directory accessibility
• Pattern file integrity

Performance Monitoring

Enable performance logging:

# In config/performance.yaml
performance_monitoring:
  enabled: true
  track_execution_time: true
  alert_on_slow_hooks: true
  target_times:
    session_start: 50    # ms
    pre_tool_use: 200    # ms  
    post_tool_use: 100   # ms
    other_hooks: 100     # ms

Common Error Messages

"Hook timeout exceeded"

• Cause: Hook execution taking longer than 10-15 seconds (settings.json timeout)
• Solution: Check performance issues section above

"YAML load failed"

• Cause: Invalid YAML syntax in configuration files
• Solution: Validate YAML files using Python or online validator

"Pattern detection failed"

• Cause: Issues with pattern files or pattern_detection.py
• Solution: Check pattern file sizes and YAML validity

"Learning engine initialization failed"

• Cause: Cache directory issues or learning data corruption
• Solution: Clear cache and reset learning data

"MCP intelligence routing failed"

• Cause: MCP server configuration or availability issues
• Solution: Check MCP server status and configuration

Getting Help

Log Analysis

Logs are written to cache/logs/ with daily rotation (30-day retention). Check recent logs for detailed error information.

Clean Installation

To reset to clean state:

# Backup any custom patterns first
rm -rf cache/
rm -rf patterns/learned/
# Restart Claude Code session

Configuration Reset

To reset all configurations to defaults:

git checkout config/*.yaml
# Or restore from backup if modified

The system is designed to be resilient with conservative defaults. Most issues resolve with basic file permission fixes and configuration validation.