Petbot/TROUBLESHOOTING.md

# PetBot Troubleshooting Guide

## Common Installation Issues

### Issue 1: externally-managed-environment Error

**Error Message:**
```
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
```

**Cause:** Modern Python installations (3.11+) prevent direct pip installations to avoid conflicts with system packages.

**Solutions:**

#### Solution A: Use Fixed Installation Script (Recommended)
```bash
./install_prerequisites_simple.sh
```

This creates a virtual environment and installs packages there.

#### Solution B: Manual Virtual Environment Setup
```bash
# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install packages
pip install -r requirements.txt

# Run bot (while venv is active)
python run_bot_with_reconnect.py

# Deactivate when done
deactivate
```

#### Solution C: System Package Installation (Ubuntu/Debian)
```bash
# Install system packages instead
sudo apt update
sudo apt install python3-pip python3-aiosqlite python3-dotenv

# For IRC library, you may still need pip in venv or --break-system-packages
pip install --break-system-packages irc>=20.3.0
```

#### Solution D: Force Installation (Not Recommended)
```bash
pip install --break-system-packages -r requirements.txt
```

⚠️ **Warning:** This can break system Python packages.

### Issue 2: venv Module Not Found

**Error Message:**
```
ModuleNotFoundError: No module named 'venv'
```

**Solution:**
```bash
# Ubuntu/Debian
sudo apt install python3-venv

# CentOS/RHEL
sudo yum install python3-venv

# Or try alternative
sudo apt install python3-virtualenv
```

### Issue 3: Permission Denied

**Error Message:**
```
Permission denied: './install_prerequisites_simple.sh'
```

**Solution:**
```bash
chmod +x install_prerequisites_simple.sh
./install_prerequisites_simple.sh
```

### Issue 4: Python Version Too Old

**Error Message:**
```
Python 3.6.x is not supported
```

**Solutions:**

#### Ubuntu/Debian:
```bash
# Add deadsnakes PPA for newer Python
sudo apt update
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-pip

# Use specific version
python3.11 -m venv venv
```

#### CentOS/RHEL:
```bash
# Enable EPEL and install Python 3.9+
sudo yum install epel-release
sudo yum install python39 python39-pip
```

#### Manual Compilation:
```bash
# Download and compile Python (last resort)
wget https://www.python.org/ftp/python/3.11.0/Python-3.11.0.tgz
tar xzf Python-3.11.0.tgz
cd Python-3.11.0
./configure --enable-optimizations
make -j 8
sudo make altinstall
```

## Runtime Issues

### Issue 5: IRC Connection Failed

**Error Message:**
```
Could not connect to irc.libera.chat:6667
```

**Solutions:**
1. Check internet connection: `ping irc.libera.chat`
2. Try different IRC server/port
3. Check firewall settings
4. Use IRC over TLS (port 6697)

### Issue 6: Database Locked

**Error Message:**
```
sqlite3.OperationalError: database is locked
```

**Solutions:**
1. Stop all bot instances
2. Check for stale lock files: `rm -f data/petbot.db-wal data/petbot.db-shm`
3. Restart the bot

### Issue 7: Web Interface Not Accessible

**Error Message:**
```
Connection refused on port 8080
```

**Solutions:**
1. Check if bot is running
2. Verify port 8080 is not in use: `netstat -tlnp | grep 8080`
3. Try different port in webserver.py
4. Check firewall: `sudo ufw allow 8080`

### Issue 8: Module Import Errors

**Error Message:**
```
ModuleNotFoundError: No module named 'irc'
```

**Solutions:**
1. Make sure virtual environment is activated
2. Reinstall packages: `pip install -r requirements.txt`
3. Check Python path: `python -c "import sys; print(sys.path)"`

## Using Virtual Environment

### Daily Usage Pattern
```bash
# Activate virtual environment
source venv/bin/activate

# Run bot
python run_bot_with_reconnect.py

# Run tests
python test_backup_simple.py

# Deactivate when done
deactivate
```

### Or Use Wrapper Scripts
```bash
# These automatically handle venv activation
./run_petbot.sh              # Start bot
./run_petbot_debug.sh        # Debug mode
./test_petbot.sh             # Run tests
./activate_petbot.sh         # Manual activation
```

## Virtual Environment Management

### Check if Virtual Environment is Active
```bash
# Should show venv path if active
which python

# Or check environment variable
echo $VIRTUAL_ENV
```

### Recreate Virtual Environment
```bash
# Remove old venv
rm -rf venv

# Create new one
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### List Installed Packages
```bash
# Activate venv first
source venv/bin/activate

# List packages
pip list

# Show package info
pip show irc aiosqlite
```

## System-Specific Issues

### Ubuntu 22.04+ (externally-managed-environment)
- Use virtual environment (recommended)
- Or install system packages: `sudo apt install python3-aiosqlite`
- IRC library may still need pip installation

### CentOS/RHEL 8+
- Enable EPEL repository
- Install python39 or newer
- Use virtual environment

### macOS
- Install via Homebrew: `brew install python3`
- Virtual environment should work normally

### Windows
- Install Python from python.org
- Use Command Prompt or PowerShell
- Virtual environment commands:
  ```cmd
  python -m venv venv
  venv\Scripts\activate
  pip install -r requirements.txt
  ```

## Development Environment

### IDE/Editor Setup

#### VS Code
```json
{
    "python.defaultInterpreterPath": "./venv/bin/python",
    "python.terminal.activateEnvironment": true
}
```

#### PyCharm
- Set Project Interpreter to `./venv/bin/python`
- Enable "Add content roots to PYTHONPATH"

### Running Tests in IDE
Make sure to:
1. Set interpreter to venv Python
2. Set working directory to project root
3. Add project root to PYTHONPATH

## Quick Diagnosis Commands

### Check Python Setup
```bash
python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -c "import sys; print(sys.path)"
```

### Check Package Installation
```bash
# In virtual environment
python -c "import irc, aiosqlite, dotenv; print('All packages OK')"
```

### Check File Permissions
```bash
ls -la *.sh *.py
ls -la data/ backups/
```

### Check Network Connectivity
```bash
ping irc.libera.chat
telnet irc.libera.chat 6667
curl -I http://localhost:8080
```

### Check System Resources
```bash
free -h          # Memory
df -h            # Disk space
ps aux | grep python  # Running Python processes
```

## Getting Help

1. **Check Logs:** Look at console output for specific error messages
2. **Test Components:** Use individual test scripts to isolate issues
3. **Verify Environment:** Ensure virtual environment is activated
4. **Check Dependencies:** Verify all packages are installed correctly
5. **Review Documentation:** Check INSTALLATION.md for detailed setup

## Emergency Recovery

### Complete Reset
```bash
# Remove everything
rm -rf venv data/*.db backups/* logs/*

# Reinstall
./install_prerequisites_simple.sh

# Restart
./run_petbot.sh
```

### Backup Database Before Reset
```bash
# Create manual backup
cp data/petbot.db data/petbot_backup_$(date +%Y%m%d_%H%M%S).db
```

### Restore from Backup
```bash
# List available backups
ls -la backups/

# Restore (replace with actual filename)
cp backups/petbot_backup_daily_20240115_030000.db.gz /tmp/
gunzip /tmp/petbot_backup_daily_20240115_030000.db
cp /tmp/petbot_backup_daily_20240115_030000.db data/petbot.db
```

Remember: When in doubt, use the virtual environment! It solves most installation issues. 🐾