Skip to content

troubleshooting.md

Latest commit

 

History

History
363 lines (272 loc) · 6.7 KB

troubleshooting.md

File metadata and controls

363 lines (272 loc) · 6.7 KB

🔧 Troubleshooting Guide

Solutions for common issues with Codestral CLI.

🔒 SSL Certificate Issues

Problem: Certificate Verification Failed

Network error: Cannot connect to host codestral.mistral.ai:443 ssl:True [SSLCertVerificationError: (1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate')]

Solutions:

1. Automatic Fix (Recommended)

python3 fix_ssl.py

2. Manual Certificate Update

pip3 install --upgrade certifi

3. macOS Specific Fix

/Applications/Python\ 3.x/Install\ Certificates.command

4. Temporary Bypass (Development Only)

PYTHONHTTPSVERIFY=0 codestral-cli "test prompt"

🔑 API Key Issues

Problem: Authentication Failed

❌ Authentication: Invalid API key. Please check your MISTRAL_API_KEY.

Solutions:

1. Check Environment Variable

echo $MISTRAL_API_KEY
# Should output your API key

2. Set API Key

export MISTRAL_API_KEY="your-actual-api-key"

3. Create Config File

mkdir -p ~/.codestral
echo '{"api_key": "your-api-key"}' > ~/.codestral/config.json

4. Get New API Key

Visit Mistral Console to generate a new key.

🚫 Exit/Quit Issues

Problem: Can't Exit Interactive Mode

If exit, quit, or Ctrl+C don't work properly:

Solutions:

1. Multiple Exit Commands

exit
quit  
bye
q

2. Force Exit

Ctrl+C (twice if needed)
Ctrl+D (EOF signal)

3. Terminal Force Quit

Ctrl+Z (suspend)
kill %1 (kill suspended job)

📦 Installation Issues

Problem: Permission Denied

bash: ./install.sh: Permission denied

Solution:

chmod +x install.sh
./install.sh

Problem: Python Module Not Found

ModuleNotFoundError: No module named 'aiohttp'

Solutions:

1. Install Dependencies

pip3 install -r requirements.txt

2. Use Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

3. Update pip

pip3 install --upgrade pip
pip3 install -r requirements.txt

🌐 Network Issues

Problem: Connection Timeout

❌ Network issue: Request timed out. Please try again.

Solutions:

1. Check Internet Connection

ping google.com

2. Check API Status

Visit Mistral Status Page or try:

curl -I https://codestral.mistral.ai/

3. Proxy/Firewall Issues

# If behind corporate firewall, configure proxy
export HTTP_PROXY=http://your-proxy:port
export HTTPS_PROXY=https://your-proxy:port

🐛 Runtime Issues

Problem: Streaming Stops Mid-Response

The AI response cuts off unexpectedly.

Solutions:

1. Increase Token Limit

codestral-cli "your prompt" --max-tokens 2000

2. Check Rate Limits

Wait a moment and try again if you're hitting rate limits.

3. Restart CLI

Exit and restart if the session seems stuck.

Problem: Rich UI Not Working

Plain text output instead of rich formatting.

Solutions:

1. Install Rich

pip3 install rich

2. Check Terminal Compatibility

Some terminals don't support rich formatting. Try a different terminal.

3. Force Simple Mode

The CLI automatically falls back to simple text if rich isn't available.

🔄 Conversation Issues

Problem: AI Gives Irrelevant Responses

AI seems to be responding to old conversations.

Solutions:

1. Clear Conversation

clear  # In interactive mode

2. Restart CLI

exit
codestral-cli  # Start fresh

3. Remove History Files

rm -rf ~/.codestral/conversation_history.json

Problem: Tools Not Working

Commands like /explain, /review don't work.

Solutions:

1. Check Command Syntax

/explain ls -la  # Correct
explain ls -la   # Wrong - missing /

2. View Available Tools

help  # Shows all available commands and tools

🖥️ Platform-Specific Issues

macOS Issues

Python Certificate Problems

# Run Python's certificate installer
/Applications/Python\ 3.x/Install\ Certificates.command

# Or manually update
pip3 install --upgrade certifi

Permission Issues

# Fix permissions
chmod +x main.py install.sh fix_ssl.py

Windows Issues

PowerShell Execution Policy

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Path Issues

Use full paths or add to PATH:

python main.py "your prompt"

Linux Issues

Missing Dependencies

# Ubuntu/Debian
sudo apt update
sudo apt install python3-pip

# CentOS/RHEL
sudo yum install python3-pip

📊 Debug Information

Get Debug Info

# Version information
codestral-cli --version

# Configuration
codestral-cli
config  # In interactive mode

# Python environment
python3 --version
pip3 list | grep -E "(aiohttp|rich|certifi)"

# SSL certificate info
python3 -c "import ssl, certifi; print(certifi.where())"

Test Connection

# Test API connectivity  
python3 fix_ssl.py

# Test with bypass
PYTHONHTTPSVERIFY=0 codestral-cli --version

🆘 Getting Help

If you're still having issues:

  1. Check the logs - Look for error messages in the terminal output
  2. Search existing issues - Visit GitHub Issues
  3. Create a new issue - Include:
    • Your operating system
    • Python version (python3 --version)
    • Complete error message
    • Steps to reproduce
  4. Join the community - Check for community support channels

🛠️ Emergency Fixes

Nuclear Option: Fresh Install

If everything breaks:

# Remove everything
rm -rf codestral-cli
rm -rf ~/.codestral

# Fresh install
git clone https://github.com/momominds/codestral-cli.git
cd codestral-cli
./install.sh

# Reconfigure
export MISTRAL_API_KEY="your-key"

Reset Configuration

# Remove config files
rm -rf ~/.codestral

# Remove conversation history
rm -rf ~/.codestral/conversation_history.json

Check System Requirements

  • Python: 3.8+ required
  • Internet: Stable connection needed
  • Storage: ~50MB for installation
  • RAM: ~100MB during operation

💡 Prevention Tips

  1. Keep dependencies updated:

    pip3 install --upgrade -r requirements.txt

  2. Regular certificate updates:

    pip3 install --upgrade certifi

  3. Monitor API usage at Mistral Console

  4. Backup your configuration before making changes

  5. Use version control for your custom configurations