EU-Utility/docs/TROUBLESHOOTING.md

EU-Utility Troubleshooting Guide

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

Table of Contents

1. Installation Issues
2. Startup Issues
3. Hotkey Issues
4. Plugin Issues
5. UI Issues
6. Performance Issues
7. OCR Issues
8. Network Issues
9. Getting Help

---

Installation Issues

"ModuleNotFoundError: No module named 'PyQt6'"

Problem: PyQt6 is not installed.

Solution:

pip install PyQt6

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

Problem: PyQt6 installation is incomplete or corrupted.

Solution:

pip uninstall PyQt6 PyQt6-Qt6 PyQt6-sip
pip install PyQt6

Permission denied during pip install

Problem: Insufficient permissions.

Solution (Windows):

# Run Command Prompt as Administrator, then:
pip install -r requirements.txt

Solution (Linux/Mac):

pip install --user -r requirements.txt

SSL certificate verification failed

Problem: SSL certificate issues.

Solution:

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

   python --version  # Should be 3.11 or higher
   

2. Check dependencies:

   pip list | grep -i pyqt
   pip list | grep -i requests
   

3. Run with debug logging:

   python -m core.main --debug
   

4. Check log files:

   cat logs/eu_utility.log
   

"No module named 'core'"

Problem: Running from wrong directory.

Solution:

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

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

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

   cat config/plugins.json
   

2. Check logs for errors:

   grep -i "plugin" logs/eu_utility.log
   

3. Verify plugin file exists:

   ls plugins/<plugin_name>/plugin.py
   

Plugin crashes on startup

Solutions:

1. Disable the plugin temporarily
2. Check for missing dependencies:

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

   ls -la config/
   

2. Verify disk space
3. Check for JSON syntax errors:

   python -m json.tool config/plugins.json
   

"Plugin dependency not satisfied"

Solution:

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

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

   export QT_QUICK_BACKEND=software
   python -m core.main
   

UI elements overlapping

Solutions:

1. Resize overlay window
2. Adjust DPI settings:

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

# Set custom DPI scaling
export QT_SCALE_FACTOR=1.5  # 150% scaling
python -m core.main

---

Performance Issues

High CPU usage

Diagnosis:

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

   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:

   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:

   # Recommended
   pip install easyocr
   
   # Or Tesseract
   pip install pytesseract
   
   # Download Tesseract from:
   # https://github.com/UB-Mannheim/tesseract/wiki
   

2. Verify installation:

   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:

   # EasyOCR downloads models automatically
   # Just restart EU-Utility
   

OCR is slow

Solutions:

1. Use smaller screen regions
2. Reduce image resolution:

   # In plugin settings
   "ocr_scale": 0.5  # 50% resolution
   

3. Use GPU acceleration (EasyOCR):

   pip install torch torchvision  # For CUDA support
   

---

Network Issues

"Failed to connect to Nexus API"

Diagnosis:

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

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

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

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

python -m core.main --debug
# Or
export EU_DEBUG=1
python -m core.main

Reset to defaults

Reset all settings:

# Backup first
cp -r config config.backup

# Reset
rm -rf config/*

Reset specific plugin:

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

# 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

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