566 lines
10 KiB
Markdown
566 lines
10 KiB
Markdown
# 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.
|