rird 2.1.231 → 2.3.0

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,914 @@
+# RIRD CLI Troubleshooting Guide
+
+Comprehensive troubleshooting guide for common issues and solutions.
+
+## Quick Diagnosis
+
+Run the diagnostic command first:
+
+```bash
+rird health-check
+```
+
+This checks:
+- License validity
+- Python environment
+- MCP servers
+- Network connectivity
+- Disk space
+- Configuration files
+
+## Common Issues and Solutions
+
+### Installation Issues
+
+#### 1. Binary Not Found for Platform
+
+**Symptoms**:
+```
+Error: Binary for your platform (linux-arm64) not found
+```
+
+**Causes**:
+- Platform not officially supported
+- Corrupted installation
+- Incomplete download
+
+**Solutions**:
+
+```bash
+# 1. Check your platform
+uname -m              # macOS/Linux
+systeminfo | grep "System Type"  # Windows
+
+# 2. Try manual installation
+curl -fsSL https://rird.ai/install.sh | bash
+
+# 3. Use npm as fallback
+npm install -g rird-ai
+
+# 4. Verify binary location
+which rird
+ls -la ~/.rird/bin/rird
+file ~/.rird/bin/rird  # Check binary format
+```
+
+#### 2. Permission Denied
+
+**Symptoms**:
+```
+Error: Permission denied: ~/.rird/bin/rird
+```
+
+**Solution**:
+```bash
+chmod +x ~/.rird/bin/rird
+ls -la ~/.rird/bin/rird  # Should show: -rwxr-xr-x
+```
+
+#### 3. Python Not Found
+
+**Symptoms**:
+```
+Error: Python 3.8+ required but not found
+```
+
+**Installation Methods**:
+
+**macOS**:
+```bash
+# Using Homebrew
+brew install python3
+python3 --version
+
+# Or from python.org
+# Download DMG from https://www.python.org/downloads/
+```
+
+**Linux (Ubuntu/Debian)**:
+```bash
+sudo apt-get update
+sudo apt-get install python3 python3-pip
+python3 --version
+```
+
+**Linux (Fedora/RHEL)**:
+```bash
+sudo dnf install python3 python3-pip
+python3 --version
+```
+
+**Windows**:
+```cmd
+# Download from https://www.python.org/downloads/
+# Run installer, check "Add Python to PATH"
+python --version
+```
+
+**WSL**:
+```bash
+# In WSL terminal
+sudo apt-get install python3 python3-pip
+python3 --version
+```
+
+#### 4. npm Install Fails
+
+**Symptoms**:
+```
+Error: npm ERR! code E404
+```
+
+**Solutions**:
+```bash
+# 1. Update npm
+npm install -g npm@latest
+
+# 2. Clear npm cache
+npm cache clean --force
+
+# 3. Retry installation
+npm install -g rird-ai
+
+# 4. Use curl installer if npm fails
+curl -fsSL https://rird.ai/install.sh | bash
+```
+
+### License Issues
+
+#### 1. License Key Invalid
+
+**Symptoms**:
+```
+Error: Invalid license key format
+```
+
+**Solutions**:
+
+```bash
+# 1. Get correct key from dashboard
+# Visit: https://rird.ai/dashboard
+# Copy key starting with 'rird_'
+
+# 2. Remove trailing whitespace
+# WRONG: rird activate "rird_abc123 "
+# RIGHT: rird activate rird_abc123
+
+# 3. Check file for corruption
+cat ~/.rird/license.key | od -c  # Show hex
+
+# 4. Re-activate with fresh key
+rird activate YOUR_LICENSE_KEY
+```
+
+#### 2. License Expired
+
+**Symptoms**:
+```
+Error: License expired on 2025-12-31
+```
+
+**Solutions**:
+
+```bash
+# 1. Check expiration date
+rird status
+
+# 2. Renew subscription
+# Visit: https://rird.ai/dashboard
+
+# 3. Activate new key
+rird activate NEW_LICENSE_KEY
+```
+
+#### 3. Device Fingerprint Mismatch
+
+**Symptoms**:
+```
+Error: Device fingerprint does not match license
+```
+
+**Causes**:
+- Using license key on different computer
+- System hostname changed
+- Computer repurposed
+
+**Solutions**:
+
+```bash
+# 1. Check current fingerprint
+rird debug
+
+# 2. Request new license for this device
+# Visit: https://rird.ai/dashboard
+# Contact: support@rird.ai
+
+# 3. Clear local cache and retry
+rm ~/.rird/license_cache.json
+rird activate YOUR_LICENSE_KEY
+```
+
+#### 4. Could Not Reach License Server
+
+**Symptoms**:
+```
+Error: Could not reach license server
+Reason: Connection timed out
+```
+
+**Causes**:
+- Network offline
+- Firewall blocking port 443
+- DNS resolution failing
+- Geographic restrictions
+
+**Solutions**:
+
+```bash
+# 1. Check internet connection
+ping rird.ai
+
+# 2. Check DNS resolution
+nslookup rird.ai     # Windows
+dig rird.ai          # macOS/Linux
+
+# 3. Check firewall
+# Port 443 (HTTPS) must be open
+# For corporate firewall: check proxy settings
+
+# 4. Try alternate DNS
+# Change DNS to 8.8.8.8 (Google)
+# Or 1.1.1.1 (Cloudflare)
+
+# 5. Use offline mode (if cached)
+# License cache is valid for 24 hours
+rird --offline <task>
+```
+
+#### 5. License Cache Corrupted
+
+**Symptoms**:
+```
+Error: Failed to parse license cache
+```
+
+**Solution**:
+
+```bash
+# Clear cache completely
+rm ~/.rird/license_cache.json
+
+# Re-validate license
+rird status
+
+# If still failing, clear and re-activate
+rm ~/.rird/license.key ~/.rird/license_cache.json
+rird activate YOUR_LICENSE_KEY
+```
+
+### Configuration Issues
+
+#### 1. Config File Not Found
+
+**Symptoms**:
+```
+Error: Configuration file not found at ~/.rird/engine/config.yaml
+```
+
+**Solutions**:
+
+```bash
+# 1. Generate default config
+rird --setup
+
+# 2. Manually create directory
+mkdir -p ~/.rird/engine
+touch ~/.rird/engine/config.yaml
+
+# 3. Copy from backup
+cp ~/rird-backup.tar.gz .
+tar -xzf rird-backup.tar.gz
+```
+
+#### 2. Invalid YAML Syntax
+
+**Symptoms**:
+```
+Error: Failed to parse configuration
+Reason: YAML syntax error at line 10
+```
+
+**Common YAML Errors**:
+
+```yaml
+# WRONG - uses tabs instead of spaces
+llm:
+→	mode: remote  # Tab character
+
+# RIGHT - uses 2 spaces
+llm:
+  mode: remote  # Two spaces
+
+# WRONG - unquoted colons in strings
+path: C:\Users\Name\Documents
+
+# RIGHT - quote strings with special chars
+path: "C:\\Users\\Name\\Documents"
+
+# WRONG - missing required fields
+llm:
+  # mode: remote  (commented out)
+
+# RIGHT - all required fields present
+llm:
+  mode: remote
+  remote_url: https://rird.ai/api/llm
+```
+
+**Solutions**:
+
+```bash
+# 1. Validate YAML online
+# Visit: https://www.yamllint.com/
+# Paste config and check for errors
+
+# 2. Use editor with YAML validation
+# VS Code: Install "YAML" extension
+# vim: Install vim-yaml plugin
+
+# 3. Regenerate from scratch
+rm ~/.rird/engine/config.yaml
+rird --setup
+
+# 4. Check indentation
+cat -A ~/.rird/engine/config.yaml | head -20
+# ^ shows tabs, > shows nothing for spaces
+```
+
+#### 3. Unknown Configuration Option
+
+**Symptoms**:
+```
+Warning: Unknown configuration option: custom_field
+```
+
+**Solutions**:
+
+```bash
+# 1. Check supported options
+rird debug config
+
+# 2. Remove unsupported option from config
+# Edit ~/.rird/engine/config.yaml
+# Remove the unknown field
+
+# 3. Check documentation
+# View complete reference: https://rird.ai/docs/config
+```
+
+#### 4. Provider API Key Issues
+
+**Symptoms**:
+```
+Error: Anthropic API key missing
+Error: OpenAI API key not configured
+```
+
+**Solutions**:
+
+```bash
+# Option 1: Environment variables (recommended for CI/CD)
+export ANTHROPIC_API_KEY="sk-ant-..."
+export OPENAI_API_KEY="sk-..."
+rird <task>
+
+# Option 2: Config file
+# Edit ~/.rird/engine/rird.json
+{
+  "provider": {
+    "anthropic": {
+      "options": {
+        "apiKey": "sk-ant-..."
+      }
+    }
+  }
+}
+
+# Option 3: Interactive setup
+rird --setup
+
+# Option 4: Check what's configured
+rird debug config | grep -i api
+```
+
+### Runtime Issues
+
+#### 1. Out of Memory (OOM)
+
+**Symptoms**:
+```
+Error: JavaScript heap out of memory
+Error: FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed
+```
+
+**Causes**:
+- Processing large files
+- Complex analysis tasks
+- Multiple concurrent operations
+- Memory leak in MCP server
+
+**Solutions**:
+
+```bash
+# Increase heap size
+export NODE_OPTIONS="--max-old-space-size=4096"
+rird <task>
+
+# Or set higher
+NODE_OPTIONS="--max-old-space-size=8192" rird <task>
+
+# Check system memory
+free -h                    # Linux
+vm_stat                    # macOS
+wmic OS get TotalVisibleMemorySize  # Windows
+
+# Kill other apps consuming memory
+# Restart computer if persistent
+
+# Simplify task
+# Process smaller files first
+# Break complex analysis into steps
+```
+
+#### 2. Task Timeout
+
+**Symptoms**:
+```
+Error: Task timed out after 30000ms
+```
+
+**Causes**:
+- Slow network
+- Complex task requiring long processing
+- Browser automation waiting on slow site
+- System resource constraints
+
+**Solutions**:
+
+```bash
+# Increase timeout in config
+# Edit ~/.rird/engine/config.yaml
+browser:
+  timeout: 60000  # 60 seconds
+
+execution:
+  task_timeout: 600000  # 10 minutes
+
+# Or via environment variable
+export RIRD_TIMEOUT=60000
+rird <task>
+
+# Simplify task
+# Break into smaller sub-tasks
+# Remove unnecessary steps
+
+# Check network speed
+speedtest-cli
+ping -c 10 google.com  # macOS/Linux
+```
+
+#### 3. Network Error
+
+**Symptoms**:
+```
+Error: Network connection failed
+Error: ECONNREFUSED
+```
+
+**Causes**:
+- Offline/poor internet
+- Firewall blocking
+- API server down
+- DNS issues
+
+**Solutions**:
+
+```bash
+# 1. Check internet connection
+ping 8.8.8.8
+curl https://www.google.com
+
+# 2. Check DNS
+nslookup rird.ai
+# or
+host rird.ai
+
+# 3. Check firewall
+# Windows: netsh advfirewall show allprofiles
+# macOS: sudo pfctl -s all
+# Linux: sudo ufw status
+
+# 4. Check RIRD API status
+curl https://status.rird.ai/api/v1/status
+
+# 5. Use proxy if behind corporate firewall
+export RIRD_PROXY="http://proxy.company.com:8080"
+rird <task>
+
+# 6. Wait and retry
+# If RIRD API is having issues
+sleep 5
+rird <task>
+```
+
+#### 4. Python Environment Error
+
+**Symptoms**:
+```
+Error: ModuleNotFoundError: No module named 'httpx'
+Error: ImportError: cannot import name 'setup'
+```
+
+**Causes**:
+- Missing Python dependencies
+- Wrong Python version
+- Virtual environment issue
+
+**Solutions**:
+
+```bash
+# Check Python version
+python3 --version  # Should be 3.8+
+
+# Install missing packages
+pip3 install httpx loguru Pillow nodriver fastmcp
+
+# Or install all dependencies
+pip3 install -r ~/.rird/requirements.txt
+
+# Check installed packages
+pip3 list | grep -E 'httpx|loguru|Pillow'
+
+# Reinstall RIRD to fix dependencies
+curl -fsSL https://rird.ai/install.sh | bash
+# or
+npm install -g rird-ai@latest
+```
+
+#### 5. MCP Server Not Running
+
+**Symptoms**:
+```
+Error: MCP server not responding
+Error: Browser automation unavailable
+```
+
+**Solutions**:
+
+```bash
+# Check MCP status
+rird health-check
+
+# Restart MCP servers
+rird mcp restart
+
+# List active MCP servers
+rird mcp list
+
+# View MCP logs
+tail -100 ~/.rird/logs/mcp.log
+
+# Reinstall browser MCP
+rm -rf ~/.rird/engine/stealth-browser-mcp
+rird --setup
+```
+
+#### 6. Browser Automation Issues
+
+**Symptoms**:
+```
+Error: Browser launch failed
+Error: Timeout waiting for browser
+```
+
+**Solutions**:
+
+```bash
+# Check Chrome/Chromium installation
+which google-chrome              # Linux
+which /Applications/Google\ Chrome.app  # macOS
+where chrome.exe                 # Windows
+
+# For Chrome not found:
+# macOS: brew install google-chrome
+# Ubuntu: sudo apt-get install google-chrome-stable
+# Windows: Download from google.com/chrome
+
+# Check browser config
+cat ~/.rird/engine/config.yaml | grep -A5 browser
+
+# Disable headless mode to see what's happening
+# Edit config: headless: false
+
+# Clear browser cache
+rm -rf ~/.rird/cache/browser-*
+
+# Test browser directly
+# This should open a browser window
+google-chrome --version
+```
+
+## Debug Mode
+
+### Enable Debug Logging
+
+```bash
+# Show verbose output
+DEBUG=1 rird <task>
+
+# Save debug output to file
+DEBUG=1 rird <task> > debug.log 2>&1
+
+# View logs in real-time
+tail -f ~/.rird/logs/rird.log
+
+# Show structured logs
+DEBUG=1 rird <task> --json
+```
+
+### Collect Diagnostic Information
+
+```bash
+# Create diagnostic bundle
+cat > ~/rird-diagnostic.txt << EOF
+=== RIRD Diagnostic Report ===
+Date: $(date)
+
+System:
+$(uname -a)
+
+RIRD Version:
+$(rird --version)
+
+License Status:
+$(rird status)
+
+Configuration:
+$(rird debug config)
+
+Environment:
+$(printenv | grep RIRD)
+$(printenv | grep ANTHROPIC)
+$(printenv | grep OPENAI)
+
+Python:
+$(python3 --version)
+$(pip3 list)
+
+Network:
+$(ping -c 1 rird.ai 2>&1 | head -5)
+$(nslookup rird.ai 2>&1 | head -5)
+
+Health Check:
+$(rird health-check)
+
+Recent Logs (last 50 lines):
+$(tail -50 ~/.rird/logs/rird.log)
+EOF
+
+cat ~/rird-diagnostic.txt
+```
+
+### Common Debug Patterns
+
+```bash
+# Debug license issues
+DEBUG=1 rird activate YOUR_KEY
+
+# Debug configuration loading
+DEBUG=1 rird --setup
+
+# Debug MCP servers
+DEBUG=1 rird mcp list
+
+# Debug LLM communication
+DEBUG=1 rird "simple task" | grep -i "llm\|request\|response"
+
+# Debug file operations
+DEBUG=1 rird "read my_file.txt"
+
+# Debug network requests
+DEBUG=1 rird --debug <task> 2>&1 | grep -i "http\|curl\|request"
+```
+
+## Log Files
+
+### Log Locations
+
+```
+~/.rird/logs/
+├── rird.log           # Main application log
+├── mcp.log            # MCP server logs
+├── browser.log        # Browser automation logs
+├── network.log        # Network requests
+└── error.log          # Error log
+```
+
+### View Logs
+
+```bash
+# Main log
+tail -100 ~/.rird/logs/rird.log
+
+# Watch log in real-time
+tail -f ~/.rird/logs/rird.log
+
+# Search logs
+grep "error" ~/.rird/logs/rird.log
+grep "timeout" ~/.rird/logs/rird.log
+
+# Filter by date
+grep "2026-01-05" ~/.rird/logs/rird.log
+
+# Get last 1 hour of logs
+grep "$(date -d '1 hour ago' '+%Y-%m-%d %H')" ~/.rird/logs/rird.log
+```
+
+### Rotating Logs
+
+Logs are automatically rotated based on size and age:
+
+```yaml
+logging:
+  file: ~/.rird/logs/rird.log
+  max_size: 104857600  # 100MB
+  max_files: 10         # Keep 10 files
+```
+
+Manual log cleanup:
+
+```bash
+# Archive old logs
+tar -czf ~/rird-logs-backup.tar.gz ~/.rird/logs/
+
+# Clear logs
+rm ~/.rird/logs/*.log
+
+# Clear old logs (30+ days)
+find ~/.rird/logs -mtime +30 -delete
+```
+
+## Performance Profiling
+
+### Profile Task Execution
+
+```bash
+# Measure execution time
+time rird <task>
+
+# JSON output with metrics
+rird --json <task> | jq '.metrics'
+
+# Show performance stats
+rird --stats
+
+# Profile with strace (Linux)
+strace -c rird <task>
+
+# Profile with dtrace (macOS)
+sudo dtrace -c 'rird <task>' -o profile.txt
+```
+
+### Monitor Resources
+
+```bash
+# Continuous monitoring (macOS/Linux)
+while true; do
+  ps aux | grep rird | grep -v grep
+  sleep 1
+done
+
+# System resource usage
+top -l 1 -n 10 | grep rird  # macOS
+top -b -n 1 | grep rird      # Linux
+
+# Docker stats (if running in container)
+docker stats
+```
+
+## Getting Help
+
+### Before Contacting Support
+
+1. Run health check: `rird health-check`
+2. Enable debug mode: `DEBUG=1 rird <task>`
+3. Collect diagnostics: Use diagnostic bundle above
+4. Check documentation: https://rird.ai/docs
+5. Search issues: https://github.com/rird-ai/rird/issues
+
+### Support Channels
+
+| Channel | Response Time | Best For |
+|---------|---------------|----------|
+| Email: support@rird.ai | 24 hours | All issues |
+| GitHub Issues | Variable | Bug reports, feature requests |
+| Community Forum | Variable | General questions, tips |
+| Status Page | Real-time | Service status |
+
+### Effective Bug Reports
+
+Include:
+
+```
+1. RIRD version: rird --version
+2. Platform: uname -a
+3. Error message: (copy exact error)
+4. Steps to reproduce:
+   - Step 1
+   - Step 2
+5. Expected vs actual:
+   - Expected: What should happen
+   - Actual: What happened
+6. Logs: tail -100 ~/.rird/logs/rird.log
+7. Config: cat ~/.rird/engine/config.yaml (remove secrets)
+8. Diagnostic bundle: Include output from diagnostic command
+```
+
+Example:
+
+```
+Bug: License activation fails on Windows
+
+RIRD Version: 2.1.239
+Platform: Windows 11 x64
+Node: v18.17.0
+Python: 3.11.4
+
+Error:
+```
+Error: Could not reach license server
+Could not reach https://rird.ai/api/desktop/validate-license
+```
+
+Steps:
+1. Run: rird activate rird_abc123xyz
+2. Observe: License server validation hangs
+
+Expected: License activates immediately
+Actual: Command times out after 30 seconds
+
+Logs attached: diagnostic-bundle.txt
+```
+
+## Workarounds for Known Issues
+
+### Issue: Auto-update Conflicts on npm
+
+**Workaround**:
+```bash
+# Disable auto-updates
+export RIRD_SKIP_AUTO_UPDATE=1
+rird <task>
+
+# Manual update when needed
+npm install -g rird-ai@latest
+```
+
+### Issue: Slow on WSL with Slow Disk
+
+**Workaround**:
+```bash
+# Increase timeouts
+export RIRD_TIMEOUT=60000
+
+# Use WSL2 instead of WSL1
+# Or use native Windows version
+```
+
+### Issue: Browser Crashes on Low Memory Systems
+
+**Workaround**:
+```bash
+# Disable headless mode to reduce memory
+# Edit ~/.rird/engine/config.yaml
+# browser:
+#   headless: false
+
+# Or use cloud execution
+rird --cloud <task>
+```
+
+## Escalation Path
+
+1. **Self-service**: Run health-check, check docs
+2. **Community**: Ask on forum or GitHub
+3. **Support email**: Include diagnostic bundle
+4. **Premium support**: For pro/enterprise plans
+
+---
+
+**Can't find your issue?** Email support@rird.ai with:
+- Diagnostic bundle (see section above)
+- Steps to reproduce
+- Expected vs actual behavior
+- Screenshots if applicable