Troubleshooting

Quick fixes for common issues and log management commands.

Log Management

View Recent Logs

ranex logs show

Output:

📋 Recent CLI Logs
────────────────────────────────────────────────────────────
┌─────────────────────┬─────────┬──────────────┬────────────┐
│ Timestamp           │ Level   │ Command      │ Duration   │
├─────────────────────┼─────────┼──────────────┼────────────┤
│ 2025-11-29 14:20:00 │ INFO    │ scan         │ 145ms      │
│ 2025-11-29 14:19:55 │ INFO    │ doctor       │ 154ms      │
│ 2025-11-29 14:19:50 │ ERROR   │ govern check │ 12ms       │
└─────────────────────┴─────────┴──────────────┴────────────┘

Filter Logs

# By command
ranex logs show --command scan

# By level
ranex logs show --level ERROR

# By time
ranex logs show --since 1h

# More entries
ranex logs show --limit 50

Watch Logs (Real-Time)

ranex logs tail

Press Ctrl+C to stop.

Search Logs

ranex logs search "error"
ranex logs search "scan failed"

Export Logs

ranex logs export ranex-logs.txt

Log Statistics

Common Issues

"ranex: command not found"

Cause: Python scripts folder not in PATH

Fix (Mac/Linux):

export PATH="$HOME/.local/bin:$PATH"

Fix (Windows):

1. Search "Environment Variables" in Start menu
2. Add %APPDATA%\Python\Python3x\Scripts to PATH

"pip: command not found"

Cause: Python not installed properly

Fix:

1. Download from python.org
2. During install, check ✅ "Add Python to PATH"
3. Restart terminal

"Permission denied"

Cause: Need admin rights

Fix:

pip install --user ranex

"ranex_mcp not found"

Cause: MCP binary not in PATH

Fix:

# Find the binary
find ~/.local -name "ranex_mcp" 2>/dev/null

# Use full path in IDE config

"No active task"

Cause: No task started

Fix:

ranex task start my-feature

"Code generation is LOCKED"

Cause: You're in Requirements or Design phase

Fix:

# Check current phase
ranex task status

# Move to implementation when ready
ranex task build

Configuration Issues

Reset configuration:

ranex config reset

View current config:

ranex config show

Edit config:

ranex config edit

System Health Check

Run diagnostics:

ranex doctor

Expected Output:

✅ Python 3.12.3
✅ Ranex Core: INSTALLED
✅ MCP Server: READY
✅ Config: VALID
✅ Database: OK

If any checks fail, the output will tell you exactly what's wrong.

Database Utilities

Check Database Status

ranex db status

Reset Database

ranex db reset

Compact Database

ranex db compact

Getting Help

Built-in Help

# General help
ranex --help

# Command-specific help
ranex scan --help
ranex task --help

Version Info

ranex --version

Next Steps

• Getting Started - Installation guide
• CLI Reference - All commands
• MCP Server Setup - IDE integration