# Troubleshooting Guide

This document provides common issues, their solutions, and debugging procedures for the MPV.Rocks Installer project.

## Table of Contents

- [Common Issues](#common-issues)
- [Windows Issues](#windows-issues)
- [Linux Issues](#linux-issues)
- [macOS Issues](#macos-issues)
- [Debugging Procedures](#debugging-procedures)
- [Getting Help](#getting-help)

---

## Common Issues

### Installer Crashes on Startup

**Symptoms:**
- Application crashes immediately on launch
- No log file created
- No error messages displayed

**Possible Causes:**
1. CPU instruction incompatibility (x86-64-v4 binary on v2 CPU)
2. Logging initialization failure
3. Missing dependencies

**Solutions:**

**1. Check CPU Compatibility**
```bash
# Windows: Check CPU features
wmic cpu get Name, MaxClockSpeed, NumberOfCores, Architecture

# Linux: Check CPU features
lscpu | grep "flags" | grep -o avx\|avx2\|avx512
```

**2. Enable Debug Mode**
```bash
# Enable debug logging
./mpv-manager --debug

# This shows initialization steps to stderr
```

**3. Check Dependencies**
```bash
# Go version
go version  # Should be 1.25 or later

# Make version
make --version
```

---

### Configuration Not Saving

**Symptoms:**
- Configuration changes not persisted
- Language preferences reset after restart
- HWA settings not applied

**Possible Causes:**
1. File permission denied
2. Config directory doesn't exist
3. Disk full
4. Concurrent write conflicts

**Solutions:**

**1. Check File Permissions**
```bash
# Windows
icacls "$USERPROFILE\.config\mpv"

# Linux/macOS
ls -la ~/.config/mpv/
```

**2. Check Disk Space**
```bash
# Windows
wmic logicaldisk get size,freespace,caption

# Linux/macOS
df -h ~/.config/mpv/
```

**3. Enable Debug Logging**
```bash
# Run with verbose mode
./mpv-manager --verbose

# Check log file
cat ~/.config/mpv/mpv-manager.log  # Linux/macOS
cat "$USERPROFILE\mpv\portable_config\mpv-manager.log"  # Windows
```

**4. Check for Concurrent Writes**
- Only one instance of installer should be running
- Close any other terminal windows or browser tabs

---

### Update Installation Fails

**Symptoms:**
- Download gets stuck or fails
- Update progress bar doesn't advance
- Error: "Failed to download update"

**Possible Causes:**
1. Network connectivity issues
2. Firewall blocking download
3. Server temporarily down
4. Invalid BLAKE3 checksum

**Solutions:**

**1. Check Network Connectivity**
```bash
# Ping release server
ping gitgud.io

# Check DNS
nslookup gitgud.io

# Test download
curl -I https://gitgud.io/mike/mpv-manager/releases/download/v1.2.3/mpv-manager-win-x86_64.exe
```

**2. Check Firewall**
```bash
# Windows Firewall
# Control Panel → Windows Defender Firewall → Allowed apps
# Add mpv-manager.exe if not present

# Third-party antivirus
# May need to add to exceptions
```

**3. Verify BLAKE3 Checksum**
```bash
# Checksum verification happens automatically
# See log for: "BLAKE3 verification passed" or "failed"
```

---

### GPU Detection Fails

**Symptoms:**
- GPU information not displayed
- Codec list shows "unknown"
- Hardware acceleration options incorrect

**Possible Causes:**
1. GPU detection command timeout
2. GPU not in database
3. Platform-specific detection fails

**Solutions:**

**1. Enable Debug Logging**
```bash
./mpv-manager --debug

# Check log for GPU detection steps
```

**2. Run GPU Detection Manually**
```bash
# Linux: Test glxinfo
glxinfo -B | grep "Device"

# Linux: Test vulkaninfo
vulkaninfo --summary | grep deviceName

# Windows: Test PowerShell
powershell -Command "Get-WmiObject Win32_VideoController | Select-Object Name, DriverVersion"

# macOS: Test system_profiler
system_profiler SPHardwareDataType
```

**3. Check GPU Database**
- Ensure GPU model is in lookup tables
- Check for alternative GPU names
- Verify GPU vendor is supported

---

## Windows Issues

### Silent Crashes on Windows

**Symptoms:**
- Application crashes before showing window
- Exception code: 0xc0000005 (ACCESS_VIOLATION)
- Works in QEMU VM but not on real hardware

**Cause:** Binary built with AVX-512 (x86-64-v4) but CPU only supports AVX2 (x86-64-v2)

**Solution:**
- Ensure Makefile has `GOAMD64=v2` for all Windows builds
- Rebuild binary with explicit baseline

```makefile
build-win-x86_64: generate-windows-resources
	@echo "Building for windows/amd64 (x86-64-v2)..."
	@mkdir -p dist
	GOOS=windows GOARCH=amd64 GOAMD64=v2 go build $(LDFLAGS) -o dist/$(BINARY_NAME)-win-x86_64.exe ./cmd/mpv-manager
```

**Verification:**
```bash
# Download v2 build
# Should work on Ryzen 1000-2000 series and Intel Core 2nd gen+

# Test on target machine
# Verify no crashes
```

---

### UAC Prompt Issues

**Symptoms:**
- File association operations fail
- Uninstall fails silently
- No UAC prompt appears

**Possible Causes:**
1. Not running as administrator
2. Batch file not elevated
3. PowerShell elevation fails

**Solutions:**

**1. Run as Administrator**
```powershell
# Right-click → Run as administrator
# Or press Ctrl+Shift while clicking
```

**2. Enable Debug Mode**
```bash
# Check for UAC-related errors in logs
./mpv-manager --debug

# Look for: "access denied", "elevation required"
```

**3. Verify UAC Status**
```powershell
# Check if running as admin
([Security.Principal.WindowsPrincipal]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltinRole]::Administrator)
```

---

### Console Size Issues

**Symptoms:**
- Menu items cut off
- Success messages not visible
- Only 2 lines visible in TUI

**Cause:** Default cmd window size (80x25)

**Solution:**
- Installer now auto-resizes to 120x40
- Should happen automatically on startup

**Manual Resize:**
```powershell
# PowerShell resize
mode 120,40

# CMD resize (temporary)
powershell -Command "$host.UI.RawUI.SuppressOutput() = $true; mode 120,40"
```

---

## Linux Issues

### Permission Denied

**Symptoms:**
- "Permission denied" errors
- Installation fails
- Configuration not saved

**Possible Causes:**
1. Not running with appropriate permissions
2. SELinux blocking operations
3. Filesystem mounted read-only

**Solutions:**

**1. Check and Fix Permissions**
```bash
# Check file permissions
ls -la ~/.config/mpv/

# Fix permissions (if writable)
chmod 755 ~/.config/mpv/
```

**2. Run with Appropriate Permissions**
```bash
# Try with sudo (for testing only)
sudo ./mpv-manager

# Check if SELinux is blocking
getenforce 0
```

**3. Check Read-Only Filesystem**
```bash
# Check if filesystem is mounted read-only
mount | grep -i read-only
```

---

### Package Manager Issues

**Symptoms:**
- Package installation fails
- Version not detected correctly
- Dependency issues

**Possible Causes:**
1. Package manager not installed
2. Package database not updated
3. Wrong package manager used

**Solutions:**

**1. Verify Package Manager**
```bash
# APT
which apt-cache
apt-cache policy mpv

# Flatpak
which flatpak
flatpak info io.mpv.Mpv

# Snap
which snap
snap list | grep mpv

# Homebrew (macOS)
which brew
brew list | grep mpv
```

**2. Update Package Database**
```bash
# APT
sudo apt update

# Flatpak
flatpak update

# Snap
snap refresh
```

**3. Check Available Packages**
```bash
# Search available packages
apt-cache search mpv
flatpak search mpv
snap search mpv
```

---

### GPU Detection Issues

**Symptoms:**
- GPU not detected
- Wrong GPU information
- Codec list incomplete

**Possible Causes:**
1. Missing GPU detection tools (vainfo, vdpauinfo, glxinfo)
2. Tools installed but not in PATH
3. Driver issues

**Solutions:**

**1. Install GPU Detection Tools**
```bash
# Ubuntu/Debian
sudo apt install vainfo vdpauinfo mesa-utils glxinfo

# Fedora/RHEL
sudo dnf install mesa-utils mesa-dri-utils vulkan-tools

# Arch
sudo pacman -S mesa-utils vulkan-tools
```

**2. Test GPU Detection Tools**
```bash
# Test vainfo
vainfo

# Test glxinfo
glxinfo -B | grep "Device"

# Test vulkaninfo
vulkaninfo --summary
```

**3. Check GPU Drivers**
```bash
# Check NVIDIA driver
nvidia-smi

# Check AMD driver
/opt/amdgpu-pro/amdgpu_pro_cli --showproductname

# Check Intel driver
sudo dmesg | grep i915
```

---

## macOS Issues

### Code Signing Issues

**Symptoms:**
- "App is damaged" message
- "Unidentified developer" message
- Installation blocked

**Possible Causes:**
1. Code signing certificate expired
2. Application not signed (macOS requirement)
3. Quarantine attribute on downloaded file

**Solutions:**

**1. Check Gatekeeper Status**
```bash
# Check if app is quarantined
xattr -l mpv-manager

# Remove quarantine attribute
xattr -d com.apple.quarantine mpv-manager
```

**2. Enable App from Anywhere**
```bash
# System Settings → Security & Privacy → Allow Anywhere
# Add terminal to exceptions if needed
```

**3. Re-download with Secure Connection**
```bash
# Download from official source
# Use HTTPS
# Verify certificate in Keychain
```

---

### Apple Silicon Issues

**Symptoms:**
- Installer crashes on M1/M2 Macs
- Rosetta errors
- Performance issues

**Possible Causes:**
1. Wrong architecture binary (x86_64 vs arm64)
2. Running under Rosetta
3. Missing VideoToolbox frameworks

**Solutions:**

**1. Use Correct Binary**
```bash
# Check architecture
uname -m
# Should return: arm64 for Apple Silicon

# Download arm64 binary
# Not: mpv-manager-darwin-x86_64 (Intel)
```

**2. Check VideoToolbox**
```bash
# Verify VideoToolbox framework is available
system_profiler SPFrameworksDataType | grep -i videotoolbox

# If missing, reinstall Xcode Command Line Tools
xcode-select --install
```

**3. Disable Rosetta**
```bash
# Check if running under Rosetta
arch
# Should show: arm64 (not x86_64)

# If running under Rosetta, uninstall and run native binary
```

---

## Debugging Procedures

### Enable Debug Mode

```bash
# Enable debug logging (shows all initialization steps)
./mpv-manager --debug

# Enable verbose mode (logs to console)
./mpv-manager --verbose

# Enable both
./mpv-manager --debug --verbose
```

### Check Log Files

**Windows:**
```powershell
# Portable config location
type "$env:USERPROFILE\mpv\portable_config\mpv-manager.log"

# Fallback location (if primary fails)
type .\mpv-manager.log
```

**Linux/macOS:**
```bash
# Config location
cat ~/.config/mpv/mpv-manager.log

# Watch log in real-time
tail -f ~/.config/mpv/mpv-manager.log
```

### Run Diagnostic Tests

**Windows:**
```powershell
# Run diagnostic binary (if available)
.\test-minimal.exe
.\test-log.exe
.\test-platform.exe
```

**Linux:**
```bash
# Run with strace (advanced)
strace -e trace=open,openat,read,write ./mpv-manager
```

### Generate Core Dump

**Windows:**
```powershell
# Enable WER (Windows Error Reporting)
# Control Panel → System → About → Advanced System Settings
# Select: "Write debugging information"
```

**Linux:**
```bash
# Enable core dumps
ulimit -c unlimited

# Run with gdb
gdb -ex core ./mpv-manager
```

### Memory Profiling

```bash
# Run with memory profile
./mpv-manager --memprofile=mem.prof

# Analyze profile
go tool pprof mem.prof
```

---

## Getting Help

### Collect Information

Before reporting an issue, collect:

1. **System Information:**
   - OS version and architecture
   - CPU model and features
   - GPU model and driver version
   - Available memory

2. **Issue Description:**
   - What were you doing when it happened?
   - What error message did you see (if any)?
   - Can you reproduce the issue?

3. **Log Files:**
   - Attach installer log file
   - Attach system logs if relevant

4. **Steps to Reproduce:**
   - Detailed step-by-step instructions

5. **Expected vs Actual:**
   - What did you expect to happen?
   - What actually happened?

### Reporting Channels

1. **GitHub Issues:** Report bugs at https://gitgud.io/mike/mpv-manager/issues
2. **Discussions:** Ask questions in Discussions tab
3. **Documentation:** Check existing documentation first
4. **Community:** Ask in community channels

### Useful Commands for Bug Reports

```bash
# Get version
./mpv-manager --version

# Get system info
./mpv-manager --debug 2>&1 | head -50

# Check log file location
cat ~/.config/mpv/mpv-manager.log

# Get installed apps config
cat ~/.config/mpv/installed_apps.json
```

---

## Preventative Measures

### Before Installation

1. [ ] Close other applications (especially media players)
2. [ ] Update operating system and drivers
3. [ ] Disable antivirus temporarily
4. [ ] Ensure adequate disk space (100+ MB)
5. [ ] Backup existing MPV configuration

### During Installation

1. [ ] Don't interrupt installation process
2. [ ] Wait for completion messages
3. [ ] Read error messages carefully
4. [ ] Keep debug log handy if issues occur

### After Installation

1. [ ] Test basic MPV playback
2. [ ] Check configuration applied correctly
3. [ ] Verify file associations work
4. [ ] Report any issues promptly

---

## Known Issues

### Platform-Specific Known Issues

**Windows:**
- OneDrive folder redirection may cause config issues
- Windows Defender may slow initial scan
- Some corporate policies block UAC elevation

**Linux:**
- Flatpak may have portal issues (user approval required)
- AppImages may take time to index
- Some distros have older package versions

**macOS:**
- Gatekeeper may delay first launch
- Code signing requires Apple Developer account
- VideoToolbox framework version dependencies

### Workarounds

**OneDrive Issues:**
```bash
# Disable OneDrive for MPV config
# Use local file path instead of OneDrive path
```

**Windows Defender:**
```powershell
# Add installer to exclusions
# Or temporarily disable real-time protection
```

---

## Quick Reference

### Common Error Messages

| Error | Cause | Solution |
|--------|---------|----------|
| "Permission denied" | File permissions | Run as admin/sudo, fix permissions |
| "Access denied" | UAC required | Run as administrator |
| "File not found" | Missing dependency | Install missing package/tool |
| "Connection refused" | Network/firewall | Check network, disable firewall |
| "Checksum failed" | Corrupted download | Re-download file |
| "Configuration not saved" | Disk full/permissions | Check disk space, fix permissions |
| "Unknown GPU" | GPU not in database | Report GPU model, enable debug |

### Exit Codes

| Code | Meaning | Action |
|-------|-----------|--------|
| 0 | Success | N/A |
| 1 | General error | Check logs, report issue |
| 2 | Misuse | Check command syntax |
| 127 | Command not found | Install missing dependencies |

---

## Conclusion

This troubleshooting guide provides solutions to the most common issues encountered with the MPV.Rocks Installer. For issues not covered here, check:
- [Session Summaries](docs/SESSION_SUMMARIES.md) - Detailed session procedures
- [Architecture](docs/ARCHITECTURE.md) - System architecture and design
- [Testing Guide](docs/TESTING.md) - Testing procedures and checklists

For unresolved issues, please report them with comprehensive information including system details, logs, and reproduction steps.