mirror of
https://github.com/SuperClaude-Org/SuperClaude_Framework.git
synced 2025-12-29 16:16:08 +00:00
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>
172 lines
4.4 KiB
Markdown
172 lines
4.4 KiB
Markdown
# 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](troubleshooting.md) 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**:
|
|
```bash
|
|
sudo chown -R $USER ~/.claude && chmod 755 ~/.claude
|
|
```
|
|
|
|
**Alternative**: Use user installation: `pip install --user SuperClaude`
|
|
|
|
[Detailed Help →](troubleshooting.md#common-installation-problems)
|
|
|
|
---
|
|
|
|
### 2. 🖥️ Python Version Too Old
|
|
**Error**: `ERROR: SuperClaude requires Python 3.8+`
|
|
|
|
**Quick Fix**:
|
|
```bash
|
|
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
|
|
```
|
|
|
|
[Detailed Help →](troubleshooting.md#python-version-compatibility)
|
|
|
|
---
|
|
|
|
### 3. 🖥️ Component Installation Failed
|
|
**Error**: `ERROR: Component 'mcp' installation failed`
|
|
|
|
**Quick Fix**:
|
|
```bash
|
|
python3 -m SuperClaude install --components core
|
|
python3 -m SuperClaude install --components mcp --force
|
|
```
|
|
|
|
[Detailed Help →](troubleshooting.md#component-installation-failures)
|
|
|
|
---
|
|
|
|
### 4. 💬 Commands Not Working in Claude Code
|
|
**Error**: `/sc:help` command not recognized
|
|
|
|
**Quick Fix**:
|
|
1. Restart Claude Code completely
|
|
2. Verify installation: `cat ~/.claude/CLAUDE.md | head -5`
|
|
3. If empty, reinstall: `python3 -m SuperClaude install --force`
|
|
|
|
[Detailed Help →](troubleshooting.md#command-execution-problems)
|
|
|
|
---
|
|
|
|
### 5. 🖥️ "SuperClaude" Command Not Found
|
|
**Error**: `command not found: SuperClaude`
|
|
|
|
**Quick Fix**:
|
|
```bash
|
|
# Try lowercase:
|
|
superclaude --version
|
|
# Or use module form:
|
|
python3 -m SuperClaude --version
|
|
```
|
|
|
|
[Detailed Help →](troubleshooting.md#command-not-found)
|
|
|
|
---
|
|
|
|
### 6. 🖥️ Windows Path Problems
|
|
**Error**: `Cannot find file 'C:\Users\name\.claude\CLAUDE.md'`
|
|
|
|
**Quick Fix**:
|
|
```cmd
|
|
set CLAUDE_CONFIG_DIR=C:\Users\%USERNAME%\.claude
|
|
python -m SuperClaude install --install-dir "%CLAUDE_CONFIG_DIR%"
|
|
```
|
|
|
|
[Detailed Help →](troubleshooting.md#windows-platform-issues)
|
|
|
|
---
|
|
|
|
### 7. 💬 Commands Hang or Timeout
|
|
**Error**: Commands start but never complete
|
|
|
|
**Quick Fix**:
|
|
1. Press Ctrl+C to cancel
|
|
2. Try smaller scope: `/sc:analyze src/` instead of entire project
|
|
3. Restart Claude Code session
|
|
|
|
[Detailed Help →](troubleshooting.md#command-timeout-or-hanging)
|
|
|
|
---
|
|
|
|
### 8. 🖥️ Node.js Missing for MCP Servers
|
|
**Error**: `Node.js not found` during MCP installation
|
|
|
|
**Quick Fix**:
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
[Detailed Help →](troubleshooting.md#mcp-server-connection-problems)
|
|
|
|
---
|
|
|
|
### 9. 💬 Memory/Resource Errors
|
|
**Error**: Insufficient memory or resources
|
|
|
|
**Quick Fix**:
|
|
```bash
|
|
# Clear temporary data:
|
|
rm -rf ~/.claude/tmp/ ~/.claude/cache/
|
|
# Work with smaller projects
|
|
# Close other applications
|
|
```
|
|
|
|
[Detailed Help →](troubleshooting.md#performance-problems-and-optimization)
|
|
|
|
---
|
|
|
|
### 10. 🖥️ Fresh Installation Needed
|
|
**Error**: Multiple issues, corrupted installation
|
|
|
|
**Quick Fix**:
|
|
```bash
|
|
rm -rf ~/.claude/
|
|
pip uninstall SuperClaude
|
|
pip install SuperClaude
|
|
python3 -m SuperClaude install --fresh
|
|
```
|
|
|
|
[Detailed Help →](troubleshooting.md#reset-and-recovery-procedures)
|
|
|
|
---
|
|
|
|
## Emergency Recovery
|
|
|
|
**Complete Reset** (when everything is broken):
|
|
```bash
|
|
rm -rf ~/.claude/ && pip uninstall SuperClaude && pip install SuperClaude && python3 -m SuperClaude install --fresh
|
|
```
|
|
|
|
**Test Installation**:
|
|
```bash
|
|
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](troubleshooting.md)
|
|
- **📖 Setup Help**: [Installation Guide](../Getting-Started/installation.md)
|
|
- **🆘 Report Issues**: [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
|
|
- **📧 Emergency Contact**: anton.knoery@gmail.com |