Troubleshooting Guide¶

This guide helps you resolve common issues when using SuperQode.

Table of Contents¶

Installation Issues
Agent Connection Problems
QE Analysis Failures
Performance Issues
Configuration Problems
Common Error Messages

Installation Issues¶

"ModuleNotFoundError" when running SuperQode¶

Problem:

ModuleNotFoundError: No module named 'superqode'

Solutions:

Install in development mode:
```
cd /path/to/superqode
pip install -e .
```

Check Python path:

python -c "import superqode; print('Import successful')"

Reinstall:

pip uninstall superqode
pip install superqode

OpenCode Installation Issues¶

Problem:

❌ OpenCode not found. Install with: npm i -g opencode-ai

Solutions:

Install OpenCode globally:
```
npm i -g opencode-ai
```
Verify Node.js and npm:
```
node --version
npm --version
```
Check npm permissions (macOS/Linux):
```
sudo npm i -g opencode-ai
```

Manual installation:

# Clone and install manually
git clone https://github.com/sst/opencode.git
cd opencode
npm install
npm run build
npm link  # or npm install -g .

Agent Connection Problems¶

"Agent not found" or "Agent unavailable"¶

Problem:

❌ Agent 'opencode' not found

Solutions:

Check OpenCode installation:
```
opencode --version
```

Verify agent configuration in YAML:

team:
  qe:
    roles:
      unit_tester:
        enabled: true

Restart SuperQode:
```
# Exit TUI and restart
superqode
```

"ACP connection failed"¶

Problem:

❌ ACP agent not available for unit_tester, providing graceful degradation

Solutions:

Install OpenCode:
```
npm i -g opencode-ai
```
Check OpenCode status:
```
opencode --help
```

Verify ACP adapter:

npm install -g @josephschmitt/opencode-acp  # If using ACP adapter

QE Analysis Failures¶

"No tests detected" when tests exist¶

Problem:

Verdict: 🟠 NO TESTS DETECTED - Add tests for proper validation

Solutions:

Check test file patterns:
Default patterns: **/*test* **/*spec* **/test_*
Python: test_*.py, *test*.py
JavaScript: *.test.js, *.spec.js
Run with verbose logging:
```
superqe run . --verbose
```
Check file permissions:
```
find . -name "*test*" -type f -ls
```

"Failed to parse jest JSON output"¶

Problem:

Failed to parse jest JSON output: Expecting value: line 1 column 1 (char 0)

Solutions:

This is usually harmless - it's just Jest output parsing issues
To suppress warnings, ensure proper Jest configuration
Use different test runners if needed

Deep QE not showing agent activity¶

Problem:

superqe run . --mode deep
# Nothing appears in console

Solutions:

Use verbose flag:
```
superqe run . --mode deep --verbose
```
Check OpenCode installation:
```
opencode --version
```

Verify agent roles are enabled:

team:
  qe:
    roles:
      api_tester:
        enabled: true
      security_tester:
        enabled: true

Performance Issues¶

Slow startup time¶

Problem: SuperQode takes too long to start

Solutions:

Use lazy loading (already implemented)
Check system resources:
```
top  # or htop
```
Close other memory-intensive applications

High memory usage during QE¶

Problem: QE analysis uses too much memory

Solutions:

Memory limits are already implemented (50MB per process)
Run smaller analysis scopes:
```
superqe run ./src --mode quick
```
Use worktree isolation:
```
superqe run . --worktree
```

Agent timeouts¶

Problem:

⏰ Agent analysis timed out after 30s

Solutions:

Increase timeout:
```
superqe run . --timeout 60
```
Use specific roles instead of all:
```
superqe run . -r unit_tester
```

Configuration Problems¶

YAML configuration not loading¶

Problem:

Configuration error: Invalid YAML format

Solutions:

Validate YAML syntax:

python -c "import yaml; yaml.safe_load(open('superqode.yaml'))"

Check indentation (YAML is space-sensitive)
Use online YAML validators

Roles not appearing¶

Problem: Expected roles don't show up in TUI

Solutions:

Check YAML structure:

team:
  qe:
    roles:
      unit_tester:
        enabled: true

Restart SuperQode after config changes
Use superqe init to reset configuration

Common Error Messages¶

"Another QE session is already running"¶

Problem: Multiple QE sessions conflict

Solution:

# Check running sessions
superqe status

# View session logs
superqe logs

"Permission denied" errors¶

Problem: File system access issues

Solutions:

# Check permissions
ls -la /path/to/project

# Fix permissions
chmod -R u+rwx /path/to/project

# Or run with sudo (not recommended)
sudo superqe run .

"Connection refused" for MCP servers¶

Problem: MCP servers not accessible

Solutions:

Check MCP server configuration in YAML
Verify MCP server processes are running:
```
ps aux | grep mcp
```

Restart MCP servers:

mcp:
  servers:
    filesystem:
      command: "npx -y @modelcontextprotocol/server-filesystem /tmp"

"Import error" for custom modules¶

Problem: Python path issues in QE analysis

Solutions:

Check Python environment:

which python
python -c "import sys; print(sys.path)"

Use virtual environment:

python -m venv venv
source venv/bin/activate
pip install superqode

Getting Help¶

If these solutions don't resolve your issue:

Check the logs:
```
superqe logs
```
Run with debug output:
```
superqode --debug qe run .
```
Report issues on GitHub:
GitHub Issues
Include full error messages and environment details
Email Support:
Reach out to us at info@super-agentic.ai
Community support:
Check GitHub Discussions
Join the SuperQode community

Health Check¶

Run this health check command to diagnose common issues:

python -c "
import sys
import subprocess
import shutil

print('🔍 SuperQode Health Check')
print('=' * 40)

# Check Python version
print(f'Python: {sys.version}')

# Check required packages
try:
    import textual
    print('✅ Textual available')
except ImportError:
    print('❌ Textual missing')

try:
    import rich
    print('✅ Rich available')
except ImportError:
    print('❌ Rich missing')

# Check OpenCode
if shutil.which('opencode'):
    print('✅ OpenCode available')
    try:
        result = subprocess.run(['opencode', '--version'], capture_output=True, text=True, timeout=5)
        if result.returncode == 0:
            print(f'   Version: {result.stdout.strip()}')
        else:
            print('❌ OpenCode not working')
    except:
        print('❌ OpenCode check failed')
else:
    print('❌ OpenCode not found')

# Check Node.js
if shutil.which('node'):
    try:
        result = subprocess.run(['node', '--version'], capture_output=True, text=True, timeout=5)
        print(f'✅ Node.js: {result.stdout.strip()}')
    except:
        print('❌ Node.js check failed')
else:
    print('❌ Node.js not found')

print('\\n💡 Run \"superqe run .\" to test QE functionality')
"