Upgrade Troubleshooting Guide¶

This guide helps resolve common issues during WhisperJAV upgrades.

Preflight Check Failures¶

"Insufficient disk space"¶

Error: Disk space: X.X GB available, need 5 GB

Solution: 1. Free up disk space on the drive where WhisperJAV is installed 2. Delete old files: %TEMP%\*, browser cache, old downloads 3. Run Disk Cleanup: cleanmgr

"Wrong Python environment detected"¶

Error:

Running from: C:\some\other\python
Expected:     C:\Users\...\AppData\Local\WhisperJAV

Solution: Run the upgrade script using WhisperJAV's Python:

%LOCALAPPDATA%\WhisperJAV\python.exe upgrade_whisperjav.py

"WhisperJAV GUI is running"¶

Error: GUI check failed: WhisperJAV GUI is running

Solution: 1. Close the WhisperJAV GUI window 2. If it doesn't close, open Task Manager and end: - pythonw.exe (WhisperJAV GUI) - WhisperJAV-GUI.exe 3. Try the upgrade again

"No internet connection"¶

Error: Network: no connection to GitHub

Solution: 1. Check your internet connection 2. Try accessing https://github.com in a browser 3. If behind a corporate firewall/proxy:

set HTTPS_PROXY=http://your-proxy:port
python.exe upgrade_whisperjav.py

Upgrade Execution Failures¶

"Package upgrade failed"¶

Symptoms: Upgrade stops during "Upgrading WhisperJAV package..."

Causes: - Network timeout - GitHub temporarily unavailable - pip cache corruption

Solutions:

Retry the upgrade:
```
python.exe upgrade_whisperjav.py
```

Clear pip cache and retry:

python.exe -m pip cache purge
python.exe upgrade_whisperjav.py

Use wheel-only mode (if you just need the latest code):
```
python.exe upgrade_whisperjav.py --wheel-only
```

"Dependency installation failed"¶

Symptoms: Some packages fail to install during dependency phase

Solutions:

Continue anyway - Most dependency failures are non-fatal

Install manually:

python.exe -m pip install <package-name>

"Permission denied" / "Access denied"¶

Symptoms: File operations fail

Solutions: 1. Close ALL WhisperJAV windows 2. Run upgrade from an elevated command prompt (Run as Administrator) 3. Temporarily disable antivirus real-time protection

"Could not update launcher"¶

Symptoms: Desktop shortcut not updated

This is non-fatal. WhisperJAV still works. To fix manually: 1. Right-click the desktop shortcut 2. Click Properties 3. Update the target path

Post-Upgrade Issues¶

"Import error" after upgrade¶

Symptoms: WhisperJAV won't start, shows import errors

Solutions:

Reinstall with dependencies:

python.exe -m pip install --force-reinstall git+https://github.com/meizhong986/whisperjav.git@main

Check for conflicting packages:
```
python.exe -m pip check
```

"CUDA not available" after upgrade¶

Symptoms: GPU acceleration stopped working

Cause: CPU-only PyTorch was installed over CUDA version

Solution:

REM Check your CUDA version first
nvidia-smi

REM Reinstall CUDA PyTorch (example for CUDA 12.1)
python.exe -m pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu121 --force-reinstall

Version didn't change after upgrade¶

Symptoms: --version shows old version

Solutions: 1. Clear Python's import cache:

python.exe -c "import whisperjav; print(whisperjav.__file__)"

2. Reinstall:

python.exe -m pip install --force-reinstall --no-cache-dir git+https://github.com/meizhong986/whisperjav.git@main

Advanced Options¶

Skip preflight checks¶

Use with caution - only if you know what you're doing:

python.exe upgrade_whisperjav.py --skip-preflight

Hot-patch mode¶

Only updates WhisperJAV code, skips all dependencies:

python.exe upgrade_whisperjav.py --wheel-only

Non-interactive mode¶

For scripted upgrades:

python.exe upgrade_whisperjav.py --yes

When All Else Fails¶

See Manual Rollback Guide for complete recovery options.

Reporting Issues¶

If you encounter an issue not covered here:

Open GitHub Issues
Include:
Full console output from the upgrade attempt
Windows version (winver)
Python version (python.exe --version)
Current WhisperJAV version (if known)