# EU-Utility Troubleshooting Guide

> Solutions to common problems and issues
> 
> **Version:** 2.0  
> **Last Updated:** 2025-02-14

---

## Table of Contents

1. [Installation Issues](#installation-issues)
2. [Startup Problems](#startup-problems)
3. [Hotkey Issues](#hotkey-issues)
4. [Overlay Problems](#overlay-problems)
5. [Plugin Issues](#plugin-issues)
6. [OCR Problems](#ocr-problems)
7. [Spotify Issues](#spotify-issues)
8. [Performance Issues](#performance-issues)
9. [Data Issues](#data-issues)
10. [Getting Help](#getting-help)

---

## Installation Issues

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

**Problem:** PyQt6 is not installed.

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

### "pip is not recognized"

**Problem:** Python is not in your PATH.

**Solution:**
1. Reinstall Python and check "Add Python to PATH"
2. Or add Python manually:
   - Windows: Add `C:\Python311\` and `C:\Python311\Scripts\` to PATH
   - Linux: Usually already in PATH

### "Permission denied" when installing

**Problem:** Insufficient permissions.

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

# Linux/Mac
sudo pip install -r requirements.txt
# Or use user install
pip install --user -r requirements.txt
```

### "Failed building wheel for ..."

**Problem:** Missing build tools.

**Solution:**

**Windows:**
```bash
# Install Visual C++ Build Tools
# Download from: https://visualstudio.microsoft.com/visual-cpp-build-tools/
# Or install just the C++ build tools workload
```

**Linux:**
```bash
sudo apt-get install python3-dev build-essential
```

---

## Startup Problems

### "EU-Utility won't start"

**Check these steps:**

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

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

3. **Run with verbose output:**
   ```bash
   python -m core.main 2>&1 | tee startup.log
   ```

4. **Check for conflicting processes:**
   - Open Task Manager (Windows) or Activity Monitor (Mac)
   - Look for existing EU-Utility processes
   - End them and try again

### "ImportError: cannot import name '...'"

**Problem:** Corrupted or partial installation.

**Solution:**
```bash
# Reinstall all dependencies
pip install --force-reinstall -r requirements.txt
```

### "Qt platform plugin could not be initialized"

**Problem:** Missing Qt platform plugins.

**Solution:**

**Windows:**
```bash
# Set environment variable
set QT_QPA_PLATFORM_PLUGIN_PATH=C:\Python311\Lib\site-packages\PyQt6\Qt6\plugins\platforms
```

**Linux:**
```bash
# Install platform plugins
sudo apt-get install qtbase5-dev
```

### "Floating icon not appearing"

**Problem:** Icon may be off-screen or hidden.

**Solution:**
1. Check system tray (may be minimized)
2. Reset position by deleting settings:
   ```bash
   # Windows
   del data\settings.json
   
   # Linux
   rm data/settings.json
   ```
3. Restart EU-Utility

---

## Hotkey Issues

### "Hotkeys not working"

**Common causes and solutions:**

#### 1. Keyboard library not installed
```bash
pip install keyboard
```

#### 2. Need Administrator privileges (Windows)
- Right-click on EU-Utility
- Select "Run as administrator"

#### 3. Conflicting hotkeys
- Check if other apps use the same hotkeys
- Change hotkeys in Settings

#### 4. Keyboard layout issues
- Some hotkeys may not work on non-US layouts
- Try different key combinations

### "Hotkeys work intermittently"

**Problem:** Focus or timing issues.

**Solutions:**
1. Ensure game window is focused
2. Try pressing hotkeys more deliberately
3. Check if antivirus is interfering
4. Disable Windows Game Mode (sometimes interferes)

### "Changed hotkey but still uses old one"

**Solution:**
1. Restart EU-Utility after changing hotkeys
2. Check if multiple instances are running
3. Reset settings:
   ```bash
   rm data/settings.json
   ```

---

## Overlay Problems

### "Overlay not showing"

**Checklist:**

1. **Press toggle hotkey:** `Ctrl + Shift + U`
2. **Double-click floating icon**
3. **Check if hidden:**
   - Press `Ctrl + Shift + H` to unhide
4. **Check opacity:**
   - May be set to 0% in settings
   - Reset: delete `data/settings.json`

### "Overlay shows but is blank"

**Solutions:**

1. **Check plugin selection:**
   - Click on a plugin tab on the left
   - First plugin may not have loaded

2. **Check for errors:**
   ```bash
   python -m core.main 2>&1 | grep -i error
   ```

3. **Disable problematic plugin:**
   - Start with `--safe-mode` (if available)
   - Or delete `data/settings.json` to reset

### "Overlay disappears when clicking game"

**Problem:** Click-through or focus issue.

**Solutions:**

1. **Check click-through setting:**
   - Right-click floating icon
   - Toggle "Click-through" mode

2. **Pin the overlay:**
   - Look for pin button in overlay header

3. **Windows-specific:**
   - Run EU-Utility as administrator
   - Disable "Focus Assist" in Windows settings

### "Overlay is too small/big"

**Solution:**
1. Resize by dragging edges
2. Or set size in settings:
   ```json
   {
     "overlay_width": 800,
     "overlay_height": 600
   }
   ```

### "Overlay shows on wrong monitor"

**Solution:**
1. Drag overlay to desired monitor
2. Position is saved automatically
3. Or reset position:
   ```bash
   rm data/settings.json
   ```

---

## Plugin Issues

### "Plugin not loading"

**Checklist:**

1. **Check plugin folder structure:**
   ```
   plugins/my_plugin/
   ├── __init__.py
   └── plugin.py
   ```

2. **Check for syntax errors:**
   ```bash
   python -m py_compile plugins/my_plugin/plugin.py
   ```

3. **Check plugin is enabled:**
   - Open Settings
   - Go to Plugins tab
   - Ensure checkbox is checked

4. **Check console output:**
   ```bash
   python -m core.main 2>&1 | grep -i "plugin"
   ```

### "Plugin crashes on open"

**Solutions:**

1. **Check plugin code:**
   - Look for missing imports
   - Check for undefined variables
   - Verify `get_ui()` returns a QWidget

2. **Enable debug mode:**
   ```python
   # Add to your plugin
   def get_ui(self):
       try:
           # Your code
       except Exception as e:
           print(f"[{self.name}] Error: {e}")
           import traceback
           traceback.print_exc()
   ```

3. **Test in isolation:**
   - Disable all other plugins
   - Test one plugin at a time

### "Plugin settings not saving"

**Solution:**
```python
# Ensure you're using the config dict
def initialize(self):
    self.my_setting = self.get_config('my_setting', default_value)

def shutdown(self):
    self.set_config('my_setting', self.my_setting)
    super().shutdown()
```

### "Plugin hotkey not working"

**Checklist:**
1. Hotkey format: `"ctrl+shift+x"` (lowercase, no spaces)
2. Hotkey not used by another plugin
3. Plugin is enabled
4. No syntax errors in plugin

---

## OCR Problems

### "OCR not working / No text detected"

**Solutions:**

#### 1. Install OCR engine
```bash
# EasyOCR (recommended)
pip install easyocr

# Or Tesseract
pip install pytesseract
# Also install Tesseract OCR binary from:
# https://github.com/UB-Mannheim/tesseract/wiki
```

#### 2. First run initialization
EasyOCR downloads models on first use. This may take a few minutes.

#### 3. Check game window visibility
- Ensure game window is visible (not minimized)
- Try increasing game brightness
- Close other windows that might overlap

#### 4. Test OCR directly
```python
from core.ocr_service import get_ocr_service

ocr = get_ocr_service()
if ocr.is_available():
    result = ocr.recognize()
    print(result)
else:
    print("OCR not available")
```

### "OCR is slow"

**Solutions:**

1. **Use GPU (if available):**
   ```bash
   pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
   ```

2. **Reduce capture region:**
   ```python
   # Capture smaller area
   result = self.ocr_capture(region=(x, y, width, height))
   ```

3. **Lower quality for speed:**
   ```python
   # In OCR service settings
   ocr.use_gpu = False  # If GPU is slower
   ```

### "OCR accuracy is poor"

**Solutions:**

1. **Increase game resolution**
2. **Use larger text in game**
3. **Ensure good lighting in game**
4. **Try different OCR engine:**
   ```python
   # In settings or config
   ocr_engine = "tesseract"  # or "easyocr"
   ```

---

## Spotify Issues

### "Spotify not detected"

**Solutions:**

#### Linux
```bash
# Install playerctl
sudo apt-get install playerctl

# Verify installation
playerctl --version
```

#### Windows
1. Ensure Spotify desktop app is running (not web player)
2. Try restarting Spotify
3. Check Windows Media Service is running

#### Mac
1. Ensure Spotify is running
2. Grant accessibility permissions if prompted

### "Spotify controls not working"

**Solutions:**

1. **Check Spotify is playing:**
   - Start playing music first
   - Then try controls

2. **Restart Spotify:**
   - Close Spotify completely
   - Reopen and start playing
   - Try controls again

3. **Check permissions (Mac):**
   - System Preferences > Security & Privacy > Accessibility
   - Add EU-Utility/Terminal

### "Spotify shows 'Not playing'"

**Solutions:**
1. Start playing music in Spotify first
2. Wait a few seconds for detection
3. Check if private session is enabled (disable it)

---

## Performance Issues

### "EU-Utility is laggy"

**Solutions:**

1. **Disable unused plugins:**
   - Settings > Plugins
   - Uncheck plugins you don't use

2. **Lower overlay opacity:**
   - Settings > General
   - Reduce opacity to 0.8 or lower

3. **Close overlay widgets:**
   - Close floating widgets you're not using

4. **Reduce OCR frequency:**
   - Don't use continuous OCR scanning

5. **Check CPU usage:**
   ```bash
   # Windows
   tasklist | findstr python
   
   # Linux
   top -p $(pgrep -d',' python)
   ```

### "High CPU usage"

**Common causes:**

1. **Too many plugins enabled**
2. **Continuous scanning**
3. **Background tasks running**

**Solutions:**
```python
# Add delays to periodic tasks
task_id = self.schedule_task(
    delay_ms=0,
    func=my_function,
    periodic=True,
    interval_ms=60000  # Every minute, not every second
)
```

### "Memory usage growing"

**Solutions:**

1. **Clear event history:**
   ```python
   from core.event_bus import get_event_bus
   get_event_bus().clear_history()
   ```

2. **Limit data retention:**
   - Settings > Data
   - Set retention to 7 or 30 days

3. **Restart EU-Utility periodically**

---

## Data Issues

### "Data not saving"

**Solutions:**

1. **Check disk space:**
   ```bash
   # Windows
   dir data\
   
   # Linux
   df -h data/
   ```

2. **Check permissions:**
   ```bash
   # Linux
   ls -la data/
   # Should be writable by current user
   ```

3. **Check for errors:**
   ```bash
   python -m core.main 2>&1 | grep -i "save\|write\|permission"
   ```

### "Data corrupted"

**Solution:**
1. Backup `data/` folder
2. Delete corrupted files
3. Restore from backup if available

### "Lost all my data"

**Recovery options:**

1. **Check for backups:**
   ```bash
   ls -la data/*.backup
   ls -la data/*.json.bak
   ```

2. **Check recycle bin/trash**

3. **Use file recovery tools** (if recently deleted)

### "Import not working"

**Solutions:**

1. **Check file format:**
   - Must be valid JSON
   - Must match expected structure

2. **Validate JSON:**
   ```bash
   python -m json.tool my_backup.json
   ```

3. **Check file encoding:**
   - Must be UTF-8

---

## Getting Help

### Collecting Information

Before asking for help, collect:

1. **EU-Utility version:**
   ```python
   # Check README or version file
   cat plugins/base_plugin.py | grep version
   ```

2. **Python version:**
   ```bash
   python --version
   ```

3. **Operating system:**
   ```bash
   # Windows
   ver
   
   # Linux
   uname -a
   ```

4. **Error logs:**
   ```bash
   python -m core.main 2>&1 | tee error.log
   ```

5. **Installed packages:**
   ```bash
   pip list > packages.txt
   ```

### Where to Get Help

1. **Documentation:**
   - Check `docs/` folder
   - Read relevant plugin documentation

2. **Logs:**
   - Check `data/logs/` for error logs
   - Run with verbose output

3. **Community:**
   - Entropia Universe forums
   - Discord communities
   - GitHub issues (if applicable)

### Reporting Bugs

When reporting bugs, include:

1. **What you were doing**
2. **What you expected to happen**
3. **What actually happened**
4. **Error messages** (copy-paste full error)
5. **Steps to reproduce**
6. **System information:**
   - OS version
   - Python version
   - EU-Utility version

### Template

```
**Bug Report**

**Description:**
Brief description of the issue

**Steps to Reproduce:**
1. Step one
2. Step two
3. Step three

**Expected Behavior:**
What should happen

**Actual Behavior:**
What actually happens

**Error Message:**
```
Paste full error message here
```

**System Info:**
- OS: Windows 11 / Ubuntu 22.04 / etc.
- Python: 3.11.4
- EU-Utility: 2.0.0

**Additional Context:**
Any other relevant information
```

---

## Quick Fixes

### Nuclear Option (Reset Everything)

```bash
# Backup first
cp -r data data.backup

# Reset settings
rm data/settings.json

# Reset all data (WARNING: Loses everything)
rm -rf data/*

# Restart EU-Utility
```

### Safe Mode Start

If EU-Utility won't start normally:

```bash
# Disable all plugins temporarily
mv plugins plugins_disabled
mkdir plugins
cp plugins_disabled/base_plugin.py plugins/

# Start EU-Utility
python -m core.main

# Re-enable plugins one by one
```

### Clean Reinstall

```bash
# 1. Backup data
cp -r data data_backup

# 2. Remove installation
rm -rf EU-Utility

# 3. Re-download and install
# (Follow installation instructions)

# 4. Restore data
cp -r data_backup/* EU-Utility/data/
```

---

**Still having issues?** Check the logs and ask for help with the information collected above.