fa14274ab4
## Changes Made: ### common-issues.md Redesign (552 → 171 lines, 69% reduction) - Transformed to "Top 10 Quick Fixes" format with 2-minute solutions - Removed all duplicate platform-specific content - Added clear cross-references to detailed troubleshooting guide - Focused on immediate problem resolution ### troubleshooting.md Enhancement - Added Quick Fix reference boxes linking to common-issues.md - Maintained comprehensive content for complex problems - Removed basic duplicate content covered in quick reference - Improved navigation between files ### Eliminated Content Duplication - **Permission errors**: Quick fix vs detailed diagnosis separation - **Python version issues**: Rapid solution vs comprehensive management - **Component installation**: Basic fix vs advanced dependency resolution - **Command problems**: Immediate fixes vs deep troubleshooting ### User Experience Improvements - Clear file purpose distinction (quick vs detailed help) - Progressive support pathway (2-min fixes → comprehensive guide) - Eliminated ~400 lines of redundant content - Better cross-file navigation and reference system ## Result: - No duplicate content between troubleshooting files - Faster problem resolution with clear escalation path - Improved maintainability and reduced documentation debt - Enhanced user experience with appropriate help level selection 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
4.4 KiB
Common Issues - Quick Reference
Quick Fix Guide: The 10 most common SuperClaude issues with rapid solutions. Each issue is designed to be resolved in under 2 minutes.
For Detailed Help: If these quick fixes don't work, see the Comprehensive Troubleshooting Guide for detailed solutions.
Command Context: 🖥️ Terminal Commands (for installation) vs 💬 Claude Code Commands (
/sc:for development)
Top 10 Quick Fixes
1. 🖥️ Permission Denied During Installation
Error: ERROR: Permission denied: '/home/user/.claude/CLAUDE.md'
Quick Fix:
sudo chown -R $USER ~/.claude && chmod 755 ~/.claude
Alternative: Use user installation: pip install --user SuperClaude
2. 🖥️ Python Version Too Old
Error: ERROR: SuperClaude requires Python 3.8+
Quick Fix:
python3 --version # Check current version
# If < 3.8, install newer Python:
sudo apt install python3.9 python3.9-pip # Linux
python3.9 -m pip install SuperClaude
3. 🖥️ Component Installation Failed
Error: ERROR: Component 'mcp' installation failed
Quick Fix:
python3 -m SuperClaude install --components core
python3 -m SuperClaude install --components mcp --force
4. 💬 Commands Not Working in Claude Code
Error: /sc:help command not recognized
Quick Fix:
- Restart Claude Code completely
- Verify installation:
cat ~/.claude/CLAUDE.md | head -5 - If empty, reinstall:
python3 -m SuperClaude install --force
5. 🖥️ "SuperClaude" Command Not Found
Error: command not found: SuperClaude
Quick Fix:
# Try lowercase:
superclaude --version
# Or use module form:
python3 -m SuperClaude --version
6. 🖥️ Windows Path Problems
Error: Cannot find file 'C:\Users\name\.claude\CLAUDE.md'
Quick Fix:
set CLAUDE_CONFIG_DIR=C:\Users\%USERNAME%\.claude
python -m SuperClaude install --install-dir "%CLAUDE_CONFIG_DIR%"
7. 💬 Commands Hang or Timeout
Error: Commands start but never complete
Quick Fix:
- Press Ctrl+C to cancel
- Try smaller scope:
/sc:analyze src/instead of entire project - Restart Claude Code session
8. 🖥️ Node.js Missing for MCP Servers
Error: Node.js not found during MCP installation
Quick Fix:
# Linux/macOS:
curl -fsSL https://nodejs.org/dist/v18.17.0/node-v18.17.0-linux-x64.tar.xz | tar -xJ
# Windows:
winget install OpenJS.NodeJS
9. 💬 Memory/Resource Errors
Error: Insufficient memory or resources
Quick Fix:
# Clear temporary data:
rm -rf ~/.claude/tmp/ ~/.claude/cache/
# Work with smaller projects
# Close other applications
10. 🖥️ Fresh Installation Needed
Error: Multiple issues, corrupted installation
Quick Fix:
rm -rf ~/.claude/
pip uninstall SuperClaude
pip install SuperClaude
python3 -m SuperClaude install --fresh
Emergency Recovery
Complete Reset (when everything is broken):
rm -rf ~/.claude/ && pip uninstall SuperClaude && pip install SuperClaude && python3 -m SuperClaude install --fresh
Test Installation:
python3 -m SuperClaude --version && echo "✅ Installation OK"
Test Claude Code Integration:
Type /sc:help in Claude Code - should show available commands.
Need More Help?
- 🔍 Detailed Solutions: Comprehensive Troubleshooting Guide
- 📖 Setup Help: Installation Guide
- 🆘 Report Issues: GitHub Issues
- 📧 Emergency Contact: anton.knoery@gmail.com