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)

./install_prerequisites_simple.sh

This creates a virtual environment and installs packages there.

Solution B: Manual Virtual Environment Setup

# 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)

# 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)

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:

# 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:

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:

# 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:

# Enable EPEL and install Python 3.9+
sudo yum install epel-release
sudo yum install python39 python39-pip

Manual Compilation:

# 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

# 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

# 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

# Should show venv path if active
which python

# Or check environment variable
echo $VIRTUAL_ENV

Recreate Virtual Environment

# 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

# 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:

  python -m venv venv
  venv\Scripts\activate
  pip install -r requirements.txt
  

Development Environment

IDE/Editor Setup

VS Code

{
    "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

python3 --version
python3 -c "import sys; print(sys.executable)"
python3 -c "import sys; print(sys.path)"

Check Package Installation

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

Check File Permissions

ls -la *.sh *.py
ls -la data/ backups/

Check Network Connectivity

ping irc.libera.chat
telnet irc.libera.chat 6667
curl -I http://localhost:8080

Check System Resources

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

# Remove everything
rm -rf venv data/*.db backups/* logs/*

# Reinstall
./install_prerequisites_simple.sh

# Restart
./run_petbot.sh

Backup Database Before Reset

# Create manual backup
cp data/petbot.db data/petbot_backup_$(date +%Y%m%d_%H%M%S).db

Restore from Backup

# 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. 🐾