TroubleshootingTroubleshooting

Common issues and solutions for RetroVoid.

Running into problems? This guide covers the most common issues and how to fix them.

RetroVoid Won't Launch#

Windows#

• Missing WebView2 Runtime: RetroVoid requires the Microsoft Edge WebView2 Runtime. It's normally installed automatically by the installer, but you can download it manually from Microsoft's website.
• Antivirus blocking: Some antivirus software may quarantine RetroVoid. Add an exception for the RetroVoid installation directory.

macOS#

• "App is damaged" error: This usually means Gatekeeper is blocking the app. Try running this in Terminal: xattr -cr /Applications/RetroVoid.app
• Permission denied: Go to System Settings > Privacy & Security and click "Open Anyway".

Linux#

• AppImage won't start: Make sure the file is executable: chmod +x RetroVoid-*.AppImage
• Missing dependencies: Install the required libraries:

  sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libssl-dev

• GPU driver issues: Ensure your GPU drivers are up to date. RetroVoid requires WebGL 2.0 support.

Black Screen on Startup#

If RetroVoid launches but shows a black or blank screen:

1. Update GPU drivers: outdated drivers are the most common cause.
2. Lower the 3D quality: if you can access Settings (press F1 twice), try setting 3D Quality to Performance (1x DPR).
3. Check display scaling: on Windows, try setting display scaling to 100%.

Note: RetroVoid does not have a safe mode or --no-gpu flag. The 3D rendering is core to the UI. The Performance quality tier (1x DPR) is the closest thing to a low-resource mode.

Games Won't Launch#

If clicking "Play" on a game doesn't start the emulator:

Launch Priority#

RetroVoid checks for emulators in this order:

1. Game's preferred emulator (if set via per-game override)
2. Platform's default emulator
3. Special handling (Windows direct launch, Steam URL, etc.)
4. Error if nothing is configured

Linux Desktop Environment Compatibility#

RetroVoid's game launching behavior may vary across different Linux desktop environments and window managers.

Tested and working:

• KDE Plasma (X11 and Wayland): fully compatible

Known issues:

• Hyprland: some users report issues launching Steam games via the steam:// URL protocol. Certain emulator launch arguments may also behave differently under Wayland compositors that handle window focus and process spawning differently than traditional DEs.

Workarounds:

• Try launching the game directly through Steam instead of through RetroVoid.
• If an emulator doesn't launch, try running it from a terminal first to check for error output.
• Check if your compositor has specific rules or settings for how new windows are spawned.

Note: Testing has so far been conducted on CachyOS with both Hyprland and KDE Plasma. If you experience issues on other desktop environments, please report them on the RetroVoid Discord or r/RetroVoid so we can expand compatibility.

ROMs Not Showing in Library#

If your games aren't appearing after adding a ROM directory:

1. Check file extensions: ensure your ROMs use supported extensions. See Managing Your Library for the full list per platform.
2. Verify the directory path: confirm the path in Settings is correct.
3. Check auto-scan: if auto_scan_enabled is on, games should appear on next launch. You can also trigger a manual rescan from Settings.
4. Shared extensions: files like .iso and .chd are shared across platforms. RetroVoid uses a priority order (PS2 > PS1 > GameCube > Wii > etc.) and folder name hints to determine the platform.
5. Special platforms: PS3, PS4, Wii U (Loadiine), Switch, and Windows games require manual import. See Managing Your Library.

Metadata Not Loading#

RetroVoid uses IGDB for metadata. If cover art or descriptions aren't appearing:

• Network issues: ensure you have an internet connection. IGDB requires online access.
• Wrong match: if the auto-matched metadata is for the wrong game, use the Search Different Name option to search manually.
• No results: some obscure or regional titles may not be in IGDB's database. You can enter a custom search query.
• Cover art fallback: if the high-res cover fails to download, RetroVoid falls back to a lower-resolution version.

Poor Performance#

RetroVoid UI Performance#

If the launcher itself feels sluggish:

1. Lower the 3D Quality setting to Performance or Balanced.
2. Disable Post-Processing (bloom, chromatic aberration, noise) in Settings > Appearance.
3. Disable Particles in Settings > Appearance.
4. Switch to the Minimal theme, which disables grid, particles, bloom, and holographic effects.
5. Disable the 3D Background entirely.

Emulator Performance#

Performance issues during gameplay are usually emulator-side, not RetroVoid:

• Try a different emulator. Some prioritize accuracy over speed.
• Check the emulator's own performance settings (frame skip, resolution scaling, etc.).
• Close other resource-heavy applications.

Controller Not Recognized#

If your gamepad isn't working in RetroVoid's UI:

1. Verify OS detection: make sure your controller is recognized by your OS first.
2. Press a button: RetroVoid requires a button press before recognizing a controller (this filters ghost controllers on Windows).
3. Try a different USB port or re-pair Bluetooth.
4. Restart RetroVoid with the controller already connected.
5. Check the top bar: a connected indicator with a tooltip should show your controller name.

Note: Controller buttons in RetroVoid cannot be remapped. All mappings follow the standard Gamepad API layout. For in-game controls, configure your controller through the emulator's own settings.

Error Messages#

RetroVoid displays errors via toast notifications (brief messages in the corner of the screen). Common errors:

Logs and Debugging#

RetroVoid does not write log files to disk. Diagnostic output goes to stdout and stderr only. To capture logs, launch RetroVoid from a terminal:

macOS / Linux#

# AppImage
./RetroVoid-*.AppImage 2>&1 | tee retrovoid.log
 
# macOS
/Applications/RetroVoid.app/Contents/MacOS/RetroVoid 2>&1 | tee retrovoid.log

Windows#

& "C:\Program Files\RetroVoid\RetroVoid.exe" 2>&1 | Tee-Object retrovoid.log

Tip: The database path is printed on startup, which can help verify the correct app data directory is being used.

Database Issues#

RetroVoid stores all data in a SQLite database. If you suspect database corruption:

• The database file is located at the paths listed in Configuration.
• Deleting the database will reset all settings, games, playlists, and play history. RetroVoid recreates it on next launch.
• Database migrations run automatically on startup and are safe to re-run.

Resetting RetroVoid#

If all else fails, you can reset RetroVoid to a clean state by deleting the app data directory:

# Windows
rmdir /s "%APPDATA%\RetroVoid"
 
# macOS
rm -rf ~/Library/Application\ Support/com.retrovoid.app
 
# Linux
rm -rf ~/.config/retrovoid
rm -rf ~/.local/share/retrovoid

Warning: This deletes all settings, library metadata, playlists, play history, and cached media. Your ROM files are not affected.

Getting Help#

Still stuck? Reach out to the community:

• Discord: Join the RetroVoid Discord. The #support channel is the fastest way to get help.
• Reddit: Post on r/RetroVoid for community discussion and support.

When reporting a bug, include:

1. Your operating system and version
2. Steps to reproduce the issue
3. Any error messages (screenshots or terminal output)
4. Your RetroVoid version (visible in Settings)