Troubleshooting

Common issues and solutions

Installation Issues

Perl Not Found

Error: perl: command not found

Solution:

# macOS
brew install perl

# Linux (Debian/Ubuntu)
sudo apt install perl

# Linux (Fedora)
sudo dnf install perl

Permission Denied

Error: Permission denied: /usr/local/bin/clio

Solution:

sudo chmod +x /usr/local/bin/clio

Authentication Issues

GitHub Copilot Login Fails

Error: Failed to authenticate with GitHub

Solution:

1. Verify you have an active GitHub Copilot subscription
2. Try logging out and back in: : /api logout then : /api login
3. Check browser for authorization prompt
4. Clear token cache: rm ~/.clio/.token

API Key Invalid

Error: Invalid API key for provider

Solution:

# Verify API key is set correctly
: /config show

# Re-set API key
: /api set key YOUR_NEW_API_KEY
: /config save

Runtime Issues

Tool Execution Fails

Error: Tool execution failed: file_operations

Solution:

• Check file permissions
• Verify file paths are correct
• Enable debug mode: : /debug
• Check tool timeout settings

Session Won't Resume

Error: Failed to load session

Solution:

# Check session directory
ls ~/.clio/sessions/

# Try loading specific session
: /session list
: /session switch sess_ID

# If corrupted, start new session
clio --new

Performance Issues

Slow Response Times

Causes:

• Large codebase slowing file operations
• Network latency to AI provider
• Complex tool operations

Solutions:

• Use .clioignore to exclude large directories
• Switch to faster model (GPT-3.5, Haiku)
• Use local models for privacy-sensitive work

Getting Help

• Report Issues on GitHub
• Join Discord Community
• Enable debug mode: clio --debug
• Check logs: ~/.clio/logs/

Next Steps

• Configuration - Advanced settings
• Workflows - Best practices
• Documentation Index - All guides