SuperClaude/Guides/troubleshooting-guide.md

SuperClaude Troubleshooting Guide 🔧

Quick Problem Diagnosis 🚨

Something not working? Start here for the fastest path to solutions. For working examples to compare against, see Examples Cookbook.

Immediate Solutions (Try These First)

Commands not showing up?

# Check if SuperClaude is installed
ls ~/.claude/CLAUDE.md

# If missing, reinstall
SuperClaude install

Command not working as expected?

# Try with help flag to see options
/sc:analyze --help

# Use preview mode to see what would happen
/sc:improve --preview src/file.js

# Start with smaller scope
/sc:analyze single-file.js  # instead of entire project

Analysis taking forever?

# Use focus to narrow scope
/sc:analyze --focus security src/

# Try quick depth instead of deep
/sc:analyze --depth quick large-project/

# Use compressed mode for efficiency
/sc:analyze --uc huge-codebase/

Getting weird results?

# Force safe mode for conservative execution
/sc:improve --safe-mode production-code/

# Add validation to check before doing anything
/sc:cleanup --validate --preview messy-code/

# Use explicit scope
/sc:build --scope file instead of --scope project

---

Installation & Setup Issues 🛠️

Installation Problems

"Python not found"

# Try different Python commands
python --version     # Windows often uses this
python3 --version    # Linux/macOS typically use this

# Check if Python is in PATH
which python3       # Linux/macOS
where python        # Windows

# Install Python if missing
# Ubuntu/Debian:
sudo apt update && sudo apt install python3 python3-pip

# macOS:
brew install python3

# Windows:
winget install python
# Or download from https://python.org/downloads/

"SuperClaude command not found"

# Try with explicit Python module
python3 -m SuperClaude install

# Check if it's installed
pip list | grep SuperClaude

# Install if missing
pip install SuperClaude

# Try with full path if PATH issues
/usr/bin/python3 -m SuperClaude install

"Claude Code not found"

• SuperClaude enhances Claude Code, so you need Claude Code installed first
• Visit https://claude.ai/code for installation instructions
• Make sure Claude Code is working before installing SuperClaude

"Permission denied" errors

# Check directory permissions
ls -la ~/.claude/

# Try with explicit Python path
/usr/bin/python3 -m SuperClaude install

# On Windows, run Command Prompt as Administrator
# On macOS, you might need to approve in Security & Privacy settings

MCP Server Installation Issues

"Node.js required for MCP servers"

# Check if Node.js is installed
node --version
npm --version

# Install Node.js if missing
# Ubuntu/Debian:
sudo apt update && sudo apt install nodejs npm

# macOS:
brew install node

# Windows:
winget install nodejs
# Or download from https://nodejs.org/

"MCP servers won't install"

# Install without MCP servers first
SuperClaude install
# During interactive setup, select "Skip MCP Server installation"

# Install MCP servers separately later if needed
SuperClaude install --components mcp

# Check MCP server status
SuperClaude install --diagnose

Installation fails partway through

# Try with verbose output to see what's happening
SuperClaude install --verbose

# Try a dry run first to see what would happen
SuperClaude install --dry-run

# Run system diagnostics
SuperClaude install --diagnose

# Try installing specific components only
SuperClaude install --components core commands

Platform-Specific Issues

Windows Issues:

• Use python instead of python3 if you get "command not found"
• Run Command Prompt as Administrator if you get permission errors
• Make sure Python is in your PATH environment variable
• Windows Defender might flag SuperClaude - add exclusion if needed

macOS Issues:

• Use brew install python3 if you don't have Python 3.8+
• You might need to approve SuperClaude in Security & Privacy settings
• Try using python3 explicitly instead of python
• Check that ~/.local/bin is in your PATH

Linux Issues:

• Make sure you have python3-pip installed: sudo apt install python3-pip
• You might need sudo for some package installations
• Check that ~/.local/bin is in your PATH: echo $PATH
• Some distros need python3-venv: sudo apt install python3-venv

---

Command Problems 🛠️

Commands Not Working

"Command not recognized"

# Make sure you're using the right prefix
/sc:analyze          # Correct
/analyze             # Wrong - missing sc: prefix

# Check available commands
/sc:index

# Try the command with help
/sc:troubleshoot --help

"No such file or directory"

# Use absolute paths, not relative
/sc:analyze /home/user/project/src/    # Correct
/sc:analyze ../project/src/           # May not work

# Check if file exists first
ls -la /path/to/file.js

Commands running but giving poor results

# Be more specific with scope
/sc:analyze --focus security auth.js  # Instead of just /sc:analyze auth.js

# Use appropriate depth
/sc:analyze --think complex-system/    # For complex analysis
/sc:analyze --depth quick simple.js   # For simple files

# Add context with framework flags
/sc:build --c7 react-app/            # Use Context7 for React patterns

Flag Issues

"Flag not working"

# Check spelling (common typos)
--ultracompressed    # Correct
--ultracompresed     # Wrong - typo

--agent security-engineer    # Correct  
--agent frontend-architect   # Wrong - should be frontend-architect

# Some flags need values
--scope project      # Correct
--scope             # Wrong - missing value

# Check for flag conflicts
--no-mcp --c7       # Conflict: --no-mcp overrides --c7

"Flags seem ignored"

# Explicit flags override auto-detection
/sc:analyze --agent security-engineer auth.js  # Forces security focus

# Check flag precedence
--safe-mode --optimize    # --safe-mode wins (safety first)

# Some combinations don't make sense
--no-mcp --sequential     # --no-mcp disables --sequential

Scope and Focus Issues

"Analysis too broad/narrow"

# Use scope to control breadth
--scope file         # Single file only
--scope module       # Related files
--scope project      # Entire project  
--scope system       # Cross-project

# Use focus to control domain
--focus security     # Security-specific analysis
--focus performance  # Performance-specific analysis
--focus quality      # Code quality focus

"Wrong expert activated"

# Force specific agent
/sc:analyze --agent security-engineer frontend-code.js

# Use focus to guide agent selection
/sc:analyze --focus security auth-system/

# Check what got activated and why
/sc:analyze --verbose --introspect problem-area/

---

Performance Issues ⚡

Speed Problems

"Commands too slow"

# Use compressed mode
/sc:analyze --uc large-codebase/

# Disable MCP servers if not needed
/sc:analyze --no-mcp simple-project/

# Limit scope
/sc:analyze --scope file slow-analysis.js

# Use quick depth for faster analysis
/sc:analyze --depth quick instead of --depth deep

"Context getting full"

# Enable token efficiency mode
/sc:command --uc

# This automatically activates when context >75%
# Reduces token usage by 30-50% while preserving information

"Too much output"

# Use compressed communication
/sc:analyze --uc verbose-command/

# Remove verbose flag if present
/sc:build --verbose    # Remove --verbose

# Use answer-only for simple questions
/sc:explain React hooks --answer-only

Memory and Resource Issues

"Running out of resources"

# Force safe mode (automatically manages resources)
/sc:command --safe-mode

# Control concurrency for parallel operations
/sc:analyze --delegate auto --concurrency 2

# Use efficient tools
--no-mcp          # Disable resource-heavy MCP servers
--uc              # Compress communication
--scope file      # Limit analysis scope

"System becoming unresponsive"

# Use safe mode with validation
/sc:improve --safe-mode --validate production-code/

# Limit concurrent operations
/sc:task --concurrency 1 large-operation

# Break large tasks into smaller pieces
/sc:analyze src/auth/     # Instead of entire src/

Token Usage Optimization

"Using too many tokens"

# Enable ultra-compressed mode
/sc:command --uc

# Focus on specific areas
/sc:analyze --focus performance --scope module

# Use efficient MCP combinations
--seq --c7       # Good combination for structured analysis
--all-mcp        # Avoid unless you need all capabilities

"Context limits reached"

# SuperClaude should auto-activate --uc when context >75%
# If not happening, force it:
/sc:continue --uc

# Break large operations into smaller chunks
/sc:analyze src/auth/ && /sc:analyze src/api/

# Use session management
/sc:save --checkpoint before-large-operation

---

Agent & MCP Server Issues 🤖

Agent Activation Problems

"Wrong agent activated"

# Check what triggered automatic selection
/sc:analyze --verbose --introspect file.js

# Force specific agent
/sc:analyze --agent security-engineer auth.js
/sc:build --agent frontend-architect ui-components/

# Use focus to guide agent selection
/sc:analyze --focus security        # Guides toward security-engineer
/sc:build --focus performance       # Guides toward performance-engineer

"Agent not working as expected"

# Verify agent capabilities
/sc:index --category agents

# Try with different focus
/sc:analyze --agent root-cause-analyst --focus debugging bug-report/

# Check if additional tools are needed
/sc:analyze --agent security-engineer --seq --c7 auth-system/

MCP Server Problems

"MCP server not activating"

# Check if MCP servers are installed
SuperClaude install --diagnose

# Force MCP server activation
/sc:analyze --c7 react-components/      # Force Context7
/sc:debug --seq complex-problem/        # Force Sequential
/sc:build --magic ui-components/        # Force Magic

# Check MCP server status
SuperClaude install --list-components | grep mcp

"Sequential MCP too slow"

# Sequential is designed for complex problems
# For simple tasks, disable it:
/sc:explain simple-function --no-mcp

# Use appropriate depth
/sc:debug --think simple-bug/           # Instead of --think-hard
/sc:debug --ultrathink critical-issue/  # Only for critical issues

"Context7 not finding docs"

# Make sure you're using current framework names
"React hooks"       # Good - specific and current
"old JavaScript"    # Poor - too vague

# Be specific about versions
"Next.js 14 routing"    # Good
"Next.js routing"       # Less specific

# Context7 works best with mainstream frameworks
React, Vue, Angular, Next.js, Express    # Well supported
Obscure frameworks                        # May have limited docs

"Magic MCP not generating good UI"

# Be specific about component requirements
/sc:build --magic "responsive login form with validation"

# Include design system context
/sc:build --magic --c7 "dashboard using Material-UI patterns"

# Magic works best with modern UI frameworks
"React component"     # Good
"plain HTML"         # Use native tools instead

"Playwright MCP tests failing"

# Check browser requirements
# Playwright needs browsers installed - this may happen automatically

# Be specific about test requirements
/sc:test --play "login flow with form validation"

# Start with simple tests first
/sc:test --play "page loads"    # Simple
/sc:test --play "complex user journey"    # More complex

Tool Coordination Issues

"Multiple MCP servers conflicting"

# Not all combinations work well together
--all-mcp           # Can be overwhelming, use sparingly

# Good combinations:
--seq --c7          # Sequential reasoning + official docs
--magic --c7        # UI generation + framework patterns
--seq --play        # Systematic testing approach

# Avoid unless needed:
--morph --serena --magic --seq    # Too many tools

"Auto-activation not working"

# Force the tools you want
/sc:analyze --agent security-engineer --c7 --seq auth-system/

# Use introspection to see what's happening
/sc:troubleshoot --introspect "why isn't this working?"

# Check trigger conditions
Framework code → Should activate Context7
Complex debugging → Should activate Sequential  
UI components → Should activate Magic

---

Integration Problems 🔗

Framework Integration

"SuperClaude doesn't understand my framework"

# Use Context7 for mainstream frameworks
/sc:build --c7 vue-app/
/sc:build --c7 angular-app/  
/sc:build --c7 next-js-app/

# For custom frameworks, be explicit
/sc:build "custom React setup with Vite and TypeScript"

# Include relevant files in analysis
/sc:analyze package.json tsconfig.json src/

"Not following project conventions"

# Make sure SuperClaude sees your config files
/sc:load .  # Loads project context including configs

# Point to specific patterns
/sc:analyze existing-component.js  # Show example before asking for new ones

# Use --safe mode to be conservative
/sc:improve --safe existing-code.js

Build System Issues

"Build commands not working"

# Make sure build tools are in PATH
npm --version
yarn --version  
pnpm --version

# Check if package.json has scripts
cat package.json | grep scripts

# Use specific build type
/sc:build --type prod    # Production build
/sc:build --type dev     # Development build

"Tests not running"

# Check test framework is configured
/sc:test --type unit     # For unit tests
/sc:test --type e2e      # For end-to-end tests

# Make sure test files exist
ls tests/
ls **/*.test.js

# Try with specific test runner
/sc:test jest           # If using Jest
/sc:test --play         # For browser tests

Version Control Issues

"Git operations failing"

# Always check status first
git status
git branch

# Make sure you're on a feature branch
git checkout -b feature/my-changes

# Use SuperClaude git helpers
/sc:git --smart-commit "describe your changes"
/sc:git status          # Enhanced status

"Commit messages poor quality"

# Use smart commit for better messages
/sc:git --smart-commit add .

# Be descriptive about changes
/sc:git commit "implement user authentication with JWT tokens"

# Review before committing
git diff --staged

---

Quality & Safety Issues 🛡️

Unsafe Code Generation

"Generated code breaks things"

# Always use safe mode for important code
/sc:improve --safe-mode production-code.js

# Use preview to see changes first
/sc:refactor --preview --safe legacy-system/

# Validate before applying
/sc:cleanup --validate --preview messy-code/

"Too many changes at once"

# Use iterative improvement
/sc:improve --loop --iterations 3 --safe complex-file.js

# Break into smaller scopes
/sc:improve --scope file individual-file.js
/sc:improve --scope module related-files/

# Use validation gates
/sc:refactor --validate --interactive large-changes/

"Changes don't follow project standards"

# Load project context first
/sc:load .  # Understand project patterns

# Use safe mode
/sc:improve --safe existing-code.js

# Point to examples
/sc:analyze good-example.js && /sc:improve bad-example.js

Test and Validation Problems

"Tests being disabled or skipped"

# Never acceptable - SuperClaude should never skip tests
# If this happens, it's a bug - report it

# Force test validation
/sc:test --coverage --validate

# Check for skipped tests
grep -r "skip\|disable" tests/

"Quality checks not running"

# Force quality analysis
/sc:analyze --focus quality --validate codebase/

# Run comprehensive tests
/sc:test --type all --coverage

# Use quality-focused agents
/sc:analyze --agent quality-engineer --agent refactoring-expert code/

Security Issues

"Security analysis missing vulnerabilities"

# Force security focus
/sc:analyze --focus security --agent security-engineer system/

# Use deep security analysis  
/sc:scan --ultrathink --focus security --validate critical-system/

# Check specific areas
/sc:analyze --focus security auth/ payment/ user-data/

"Generated code has security flaws"

# Always use safe mode for security-sensitive code
/sc:implement --safe-mode --focus security auth-system

# Validate security explicitly
/sc:analyze --focus security --validate generated-code.js

# Use security-focused agents
/sc:implement --agent security-engineer payment-processing

---

Advanced Troubleshooting 🔬

Systematic Problem Analysis

When basic solutions don't work, use systematic debugging:

Step 1: Gather Information

# Check system status
SuperClaude install --diagnose

# Check git status
git status && git branch

# Check project structure
/sc:load . --summary

# Verify component installation
SuperClaude install --list-components

Step 2: Isolate the Problem

# Test with minimal scope
/sc:analyze simple-file.js --no-mcp

# Test with different agents
/sc:analyze --agent learning-guide simple-problem

# Test with different tools
/sc:analyze --c7 vs /sc:analyze --seq vs /sc:analyze --no-mcp

Step 3: Use Diagnostic Mode

# Enable introspection
/sc:troubleshoot --introspect "specific problem description"

# Use verbose mode
/sc:analyze --verbose --introspect problem-area/

# Get reasoning transparency
/sc:debug --think --introspect complex-issue/

Framework Debugging

SuperClaude Behavior Issues:

# Check mode activation
/sc:command --introspect  # See which modes activated and why

# Force specific modes
/sc:brainstorm --brainstorm idea  # Force brainstorming even for clear ideas
/sc:analyze --no-modes simple-file.js  # Disable all modes

# Check agent selection logic
/sc:analyze --verbose domain-specific-code/

Integration Debugging:

# Test MCP server combinations
/sc:test --c7 --seq --magic complex-feature/    # Multiple servers
/sc:test --no-mcp simple-feature/               # No servers

# Check flag precedence
/sc:improve --safe-mode --optimize code/  # Safe mode should win

Performance Profiling

Identify Bottlenecks:

# Time operations
time /sc:analyze large-project/

# Use resource monitoring
/sc:analyze --uc --orchestrate --delegate auto huge-codebase/

# Profile tool usage
/sc:analyze --verbose --introspect slow-operation/

Optimize Performance:

# Best performance combination
/sc:analyze --uc --no-mcp --scope file --depth quick

# Best quality combination  
/sc:analyze --all-mcp --think-hard --delegate auto

# Balanced approach
/sc:analyze --c7 --seq --uc --focus specific-area

---

Getting Help 🆘

When to Escalate

Try advanced troubleshooting first:

1. Check this guide for your specific issue
2. Use --introspect mode to understand what's happening
3. Try with --safe-mode and --validate flags
4. Use minimal scope (--scope file) to isolate issues
5. Check GitHub issues for similar problems

Report bugs when:

• Commands consistently fail with error messages
• SuperClaude skips or disables tests (never acceptable)
• Security analysis misses obvious vulnerabilities
• Generated code breaks existing functionality despite --safe-mode
• MCP servers installed but not activating
• Framework installation fails with clear error messages

Bug Reporting Template

When reporting issues, include:

**Issue Description:**
[What you expected vs what happened]

**Environment:**
- Operating System: [Windows/macOS/Linux + version]
- Python Version: [python3 --version]  
- SuperClaude Version: [pip show SuperClaude]
- Claude Code Version: [claude --version]

**Command Used:**
[Exact command that caused the issue]

**Error Message:**
[Complete error message, if any]

**Steps to Reproduce:**
1. [First step]
2. [Second step]
3. [Result]

**Expected Behavior:**
[What should have happened]

**Additional Context:**
[Any other relevant information]

Community Resources

• GitHub Issues: https://github.com/SuperClaude-Org/SuperClaude_Framework/issues
• Installation Guide: /home/anton/SuperClaude_Framework/Guides/installation-guide.md
• Commands Guide: /home/anton/SuperClaude_Framework/Guides/commands-guide.md
• Agents Guide: /home/anton/SuperClaude_Framework/Guides/agents-guide.md

Self-Help Resources

Quick Reference Checks:

# See all available commands  
/sc:index

# Get help for specific command
/sc:analyze --help

# System diagnostics
SuperClaude install --diagnose

# Check what's installed
SuperClaude install --list-components

# See project status
/sc:load . --summary

---

Prevention Tips 💡

Avoiding Common Problems

Before Starting Work:

1. Always run /sc:load . to understand the project
2. Check git status and create a feature branch
3. Use --safe-mode for production code
4. Start with smaller scope and expand as needed

During Development:

1. Use --preview flags when available
2. Validate changes before applying: --validate
3. Save checkpoints: /sc:save --checkpoint "before major change"
4. Test incrementally rather than making large changes

For Complex Operations:

1. Use --think flags for systematic analysis
2. Force appropriate experts with --agent when needed
3. Break large tasks into smaller scopes
4. Use --iterative for step-by-step improvements

Resource Management:

1. Monitor context usage - auto --uc should kick in at 75%
2. Use --concurrency to control parallel operations
3. Clean up temporary files and workspace regularly
4. Use --safe-mode when resource usage is high

Best Practices

Command Usage:

• Be specific rather than vague: "analyze auth security" vs "look at this"
• Use appropriate scope: file → module → project → system
• Combine flags thoughtfully: --safe-mode --validate for production
• Let auto-activation work - manual override only when needed

Project Integration:

• Load project context before major operations: /sc:load .
• Follow existing patterns rather than imposing new ones
• Use framework-specific tools: --c7 for documented frameworks
• Respect existing test and build configurations

Quality Assurance:

• Never skip or disable tests to make things work
• Use validation flags: --validate --preview --safe-mode
• Test changes incrementally rather than all at once
• Maintain clean git history with descriptive commits

---

Quick Reference Cards 📋

Emergency Fixes

# Command not working
/sc:command --help
/sc:command --preview --safe-mode

# Installation broken
SuperClaude install --diagnose
SuperClaude install --force

# Performance issues  
/sc:command --uc --no-mcp --scope file

# Quality issues
/sc:command --safe-mode --validate --preview

# MCP servers not working
SuperClaude install --components mcp --force

Common Flag Combinations

# Safe production work
--safe-mode --validate --preview

# Fast analysis
--uc --no-mcp --depth quick

# Deep investigation  
--think-hard --seq --c7 --introspect

# UI development
--magic --c7 --agent frontend-architect

# Security work
--agent security-engineer --focus security --validate

Scope Control

--scope file          # Single file
--scope module        # Related files  
--scope project       # Entire project
--scope system        # Cross-project

--focus performance   # Performance-specific
--focus security      # Security-specific  
--focus quality       # Quality-specific
--focus architecture  # Architecture-specific

---

Related Guides

🚀 When Troubleshooting Fails (Essential)

• Installation Guide - Reinstall or fix setup issues
• Examples Cookbook - Working examples to verify functionality
• SuperClaude User Guide - Framework overview and expectations

📚 Understanding What Should Work (Recommended)

• Commands Guide - How commands should behave normally
• Agents Guide - When specialists should activate
• Behavioral Modes Guide - How automatic adaptation should work
• Session Management Guide - Session lifecycle issues

⚙️ Advanced Problem Solving (When Basics Don't Work)

• Flags Guide - Flag conflicts and optimization issues
• Best Practices Guide - Prevention patterns and optimal workflows
• Technical Architecture Guide - Internal system understanding

📖 Recommended Troubleshooting Path:

1. Try solutions in Quick Problem Diagnosis first
2. Check Examples Cookbook to verify expected behavior
3. Review Commands Guide for correct usage patterns
4. Use Best Practices Guide for prevention strategies

---

Remember: SuperClaude is designed to be helpful and safe. When in doubt, use --safe-mode --validate --preview to see what would happen before applying changes. Most issues can be resolved by being more specific about what you want and using appropriate safety flags.

Happy troubleshooting! 🚀