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, smaller models for quicker responses
  • Use local models for privacy-sensitive work

Getting Help

Next Steps