# EU-Utility Troubleshooting Guide

This guide helps you diagnose and fix common issues with EU-Utility.

## Table of Contents

1. [Installation Issues](#installation-issues)
2. [Startup Issues](#startup-issues)
3. [Hotkey Issues](#hotkey-issues)
4. [Plugin Issues](#plugin-issues)
5. [UI Issues](#ui-issues)
6. [Performance Issues](#performance-issues)
7. [OCR Issues](#ocr-issues)
8. [Network Issues](#network-issues)
9. [Getting Help](#getting-help)

---

## Installation Issues

### "ModuleNotFoundError: No module named 'PyQt6'"

**Problem:** PyQt6 is not installed.

**Solution:**
```bash
pip install PyQt6
```

### "ImportError: cannot import name 'Qt' from 'PyQt6.QtCore'"

**Problem:** PyQt6 installation is incomplete or corrupted.

**Solution:**
```bash
pip uninstall PyQt6 PyQt6-Qt6 PyQt6-sip
pip install PyQt6
```

### Permission denied during pip install

**Problem:** Insufficient permissions.

**Solution (Windows):**
```bash
# Run Command Prompt as Administrator, then:
pip install -r requirements.txt
```

**Solution (Linux/Mac):**
```bash
pip install --user -r requirements.txt
```

### SSL certificate verification failed

**Problem:** SSL certificate issues.

**Solution:**
```bash
# Windows
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org -r requirements.txt

# Or update certificates
pip install --upgrade certifi
```

---

## Startup Issues

### EU-Utility doesn't start / crashes immediately

**Checklist:**

1. **Verify Python version:**
   ```bash
   python --version  # Should be 3.11 or higher
   ```

2. **Check dependencies:**
   ```bash
   pip list | grep -i pyqt
   pip list | grep -i requests
   ```

3. **Run with debug logging:**
   ```bash
   python -m core.main --debug
   ```

4. **Check log files:**
   ```bash
   cat logs/eu_utility.log
   ```

### "No module named 'core'"

**Problem:** Running from wrong directory.

**Solution:**
```bash
# Navigate to EU-Utility root directory
cd /path/to/EU-Utility
python -m core.main
```

### "QApplication: invalid style override passed"

**Problem:** Qt style conflict.

**Solution:**
```bash
# Set default style
export QT_STYLE_OVERRIDE=fusion  # Linux/Mac
set QT_STYLE_OVERRIDE=fusion     # Windows
```

### Tray icon not appearing

**Problem:** System tray access issue.

**Solutions:**
1. Check if system tray is enabled in OS settings
2. Restart EU-Utility
3. Check taskbar settings (Windows) or panel settings (Linux)

---

## Hotkey Issues

### Hotkeys don't work in-game

**Common causes and solutions:**

1. **Game has exclusive input:**
   - Run EU-Utility as administrator (Windows)
   - Try different hotkey combinations

2. **Conflicting hotkeys:**
   - Check other running applications
   - Change hotkeys in Settings → Hotkeys

3. **Hotkey registration failed:**
   ```bash
   # Check logs for registration errors
   grep -i "hotkey" logs/eu_utility.log
   ```

### "Failed to register hotkey" error

**Solutions:**
1. Restart EU-Utility
2. Check if hotkey is used by another app
3. Try different key combination
4. Run as administrator

### Hotkeys work intermittently

**Possible causes:**
- Focus issues
- Game anti-cheat interfering
- System under heavy load

**Solutions:**
1. Ensure EU-Utility has focus before game
2. Disable game overlays that might conflict
3. Close unnecessary applications

---

## Plugin Issues

### Plugin doesn't load

**Diagnosis:**
1. Check if plugin is enabled:
   ```bash
   cat config/plugins.json
   ```

2. Check logs for errors:
   ```bash
   grep -i "plugin" logs/eu_utility.log
   ```

3. Verify plugin file exists:
   ```bash
   ls plugins/<plugin_name>/plugin.py
   ```

### Plugin crashes on startup

**Solutions:**
1. Disable the plugin temporarily
2. Check for missing dependencies:
   ```bash
   # Look for ImportError in logs
   grep -i "import" logs/eu_utility.log | grep -i error
   ```
3. Update the plugin

### Plugin settings not saving

**Solutions:**
1. Check file permissions:
   ```bash
   ls -la config/
   ```
2. Verify disk space
3. Check for JSON syntax errors:
   ```bash
   python -m json.tool config/plugins.json
   ```

### "Plugin dependency not satisfied"

**Solution:**
```bash
# Install missing dependencies
pip install <package_name>

# Or let EU-Utility handle it:
# Settings → Plugins → Install Dependencies
```

---

## UI Issues

### Overlay not visible / behind game window

**Solutions:**

1. **Toggle overlay:**
   - Press `Ctrl+Shift+U` twice
   - Or click tray icon

2. **Check "Always on top":**
   - Settings → Appearance → Always on top

3. **Run as administrator (Windows):**
   - Right-click → "Run as administrator"

4. **Window manager conflict (Linux):**
   ```bash
   # Try different window managers
   # Or use --force-x11 flag if available
   ```

### Overlay is transparent / invisible

**Solutions:**
1. Check opacity setting:
   - Settings → Appearance → Opacity
   - Set to 1.0 (fully opaque)

2. Update graphics drivers
3. Disable hardware acceleration:
   ```bash
   export QT_QUICK_BACKEND=software
   python -m core.main
   ```

### UI elements overlapping

**Solutions:**
1. Resize overlay window
2. Adjust DPI settings:
   ```bash
   # Windows
   set QT_AUTO_SCREEN_SCALE_FACTOR=1
   
   # Linux/Mac
   export QT_AUTO_SCREEN_SCALE_FACTOR=1
   ```
3. Update EU-Utility

### Text is too small / large

**Solution:**
```bash
# Set custom DPI scaling
export QT_SCALE_FACTOR=1.5  # 150% scaling
python -m core.main
```

---

## Performance Issues

### High CPU usage

**Diagnosis:**
```bash
# Check which process is using CPU
top  # Linux/Mac
tasklist  # Windows

# Check EU-Utility logs for errors
tail -f logs/eu_utility.log
```

**Solutions:**
1. Disable unused plugins
2. Reduce polling frequency in tracker plugins
3. Check for infinite loops in custom plugins
4. Update to latest version

### High memory usage

**Solutions:**
1. **Clear cache:**
   ```bash
   rm -rf data/cache/*
   ```

2. **Disable memory-heavy plugins:**
   - Chat Logger (if logging all channels)
   - Screenshot plugins

3. **Limit log history:**
   - Settings → Advanced → Max log lines

### Slow startup

**Solutions:**
1. **Reduce plugin count:**
   - Disable unused plugins
   
2. **Pre-compile Python:**
   ```bash
   python -m compileall .
   ```

3. **Use SSD for installation**

### Laggy UI

**Solutions:**
1. Disable animations:
   - Settings → Appearance → Disable animations
   
2. Reduce widget count on dashboard

3. Update graphics drivers

---

## OCR Issues

### "OCR not available" message

**Solutions:**

1. **Install OCR backend:**
   ```bash
   # Recommended
   pip install easyocr
   
   # Or Tesseract
   pip install pytesseract
   
   # Download Tesseract from:
   # https://github.com/UB-Mannheim/tesseract/wiki
   ```

2. **Verify installation:**
   ```bash
   python -c "import easyocr; print('OK')"
   ```

### OCR results are inaccurate

**Solutions:**

1. **Adjust screen region:**
   - Make region smaller and focused
   - Avoid areas with lots of visual noise

2. **Improve lighting in game:**
   - Increase brightness
   - Use high contrast themes

3. **Try different OCR backend:**
   - EasyOCR: Best for general text
   - Tesseract: Best for numbers
   - PaddleOCR: Best for complex layouts

4. **Update OCR models:**
   ```bash
   # EasyOCR downloads models automatically
   # Just restart EU-Utility
   ```

### OCR is slow

**Solutions:**
1. Use smaller screen regions
2. Reduce image resolution:
   ```python
   # In plugin settings
   "ocr_scale": 0.5  # 50% resolution
   ```
3. Use GPU acceleration (EasyOCR):
   ```bash
   pip install torch torchvision  # For CUDA support
   ```

---

## Network Issues

### "Failed to connect to Nexus API"

**Diagnosis:**
```bash
# Test connectivity
curl https://api.entropianexus.com
ping api.entropianexus.com
```

**Solutions:**
1. Check internet connection
2. Verify API status: https://status.entropianexus.com
3. Check firewall settings
4. Try different DNS server

### "SSL certificate verify failed"

**Solution:**
```bash
# Update certificates
pip install --upgrade certifi

# Or disable verification (not recommended)
# Settings → Advanced → Verify SSL: Off
```

### Slow API responses

**Solutions:**
1. Enable caching:
   - Settings → Nexus API → Enable caching
   
2. Increase cache duration:
   ```json
   {
     "nexus": {
       "cache_duration": 3600
     }
   }
   ```

3. Check network connection

---

## Getting Help

### Before asking for help:

1. **Check this troubleshooting guide**
2. **Search existing issues:** https://github.com/ImpulsiveFPS/EU-Utility/issues
3. **Check FAQ:** docs/FAQ.md
4. **Collect information:**
   ```bash
   # System info
   python --version
   pip list
   
   # EU-Utility logs
   cat logs/eu_utility.log | tail -100
   
   # Config
   cat config/settings.json
   cat config/plugins.json
   ```

### How to report an issue:

Create a GitHub issue with:

1. **Description:** What happened?
2. **Steps to reproduce:** How can we recreate the issue?
3. **Expected behavior:** What should have happened?
4. **Actual behavior:** What actually happened?
5. **Environment:**
   - OS version
   - Python version
   - EU-Utility version
6. **Logs:** Relevant log entries
7. **Screenshots:** If UI-related

### Debug mode

Enable debug logging:
```bash
python -m core.main --debug
# Or
export EU_DEBUG=1
python -m core.main
```

### Reset to defaults

**Reset all settings:**
```bash
# Backup first
cp -r config config.backup

# Reset
rm -rf config/*
```

**Reset specific plugin:**
```bash
# Remove plugin settings
python -c "
import json
with open('config/plugins.json') as f:
    config = json.load(f)
config['settings']['plugin.name'] = {}
with open('config/plugins.json', 'w') as f:
    json.dump(config, f, indent=2)
"
```

---

## Quick Fixes

### Nuclear option (complete reset)

```bash
# Backup your data first!
cp -r data data.backup
cp -r config config.backup

# Reset everything
rm -rf data/* config/*

# Restart EU-Utility
python -m core.main
```

### Common one-liners

```bash
# Fix permissions (Linux/Mac)
chmod -R u+rw config data logs

# Clear cache
rm -rf data/cache/*

# Reset window position
rm config/window_position.json

# Update all packages
pip install --upgrade -r requirements.txt
```

---

**Still having issues?** Open an issue on GitHub with your logs and system information.