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
• AppImage reports a FUSE error: AppImages need FUSE to mount themselves. On Ubuntu 22.04 and newer:

  sudo apt install libfuse2

• Missing dependencies after installing the .deb: Run sudo apt-get install -f to pull them in.
• 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.

License Activation#

On first launch RetroVoid asks for your license key. Paste it in and click Activate License.

• "Activation failed. Please check your license key.": confirm the key matches the one from your purchase, including the dashes, and that the machine is online. Activation is the one step that always needs internet.
• Checking status later: Settings > License shows Licensed or Not Licensed, a masked copy of your key, and when it was last verified.
• Re-checking on demand: click Validate Now.
• Moving to another machine: click Deactivate, confirm, and activate with the same key on the new machine.
• No key yet: the activation screens link to retrovoid.net.

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. The platform's default emulator
2. Special handling (Windows direct launch, Steam URL)
3. Error if nothing is configured

When the error is that no emulator is configured, the game's detail view lists every emulator that supports that platform under Launch with Emulator so you can launch with one immediately. To make the choice permanent, set the platform default.

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 > Library is correct, and use that folder's own Scan button to test it in isolation.
3. Check auto-scan: when Auto-scan on Launch is on, games appear on the next start. You can also click Scan Library at any time.
4. Shared extensions: files like .iso and .chd are shared across platforms. Set the folder's platform dropdown explicitly. Without it, RetroVoid looks for a platform name in the folder path and then falls back to a priority order (PS2 > PS1 > GameCube > Wii > and so on).
5. Deliberately skipped files: .bin files that sit next to a .cue or .gdi are treated as disc tracks, not games, and neogeo.zip is skipped as a BIOS file.
6. Folder-based platforms: PS3, PS4, Wii U (Loadiine), and PS Vita games are detected as folders, so the folder above them must be in your scan paths.
7. Manual import only: Switch and Windows games, and PS3 titles installed from a PKG, have to be added by hand. See Managing Your Library.

Metadata Not Loading#

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

• Nothing was requested: library scans never fetch metadata. Trigger it yourself, either per game from its detail view or in bulk with Scrape All Games in Settings > Metadata.
• Credentials missing or rejected: IGDB needs your own free Twitch Client ID and Client Secret. Enter them in Settings > Metadata and click Validate & Save. See Configuration for the walkthrough.
• 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 Search IGDB (pick manually), or Search Different Name to retry with another title.
• No results: some obscure or regional titles may not be in IGDB's database. You can enter a custom search query, which searches across all platforms rather than just the game's own.
• Image quality fallback: if the requested image tier isn't available, RetroVoid falls back to a lower-resolution variant.
• Wrong art stuck on a game: right-click the game and choose Remove Cover Art, or delete individual screenshots from the Media tab. Re-fetching metadata restores IGDB screenshots.

Steam Issues#

• No Steam games listed: Scan Library in Settings > Steam Import reads your local Steam installation, so Steam must be installed and the games must be fully installed, not merely owned. If the tab says "Steam not detected", RetroVoid could not find your Steam folder.
• "Invalid credentials": check the API key and the 64-bit Steam ID, and make sure your Steam profile privacy is set to Public.
• Play time is behind: Steam publishes a session's play time a minute or two after the game closes. RetroVoid retries for a while after you return to it, and Update Steam Data forces a refresh.
• Last played looks wrong: RetroVoid takes the newer of your Steam account record and your local Steam client's record, and only ever moves the date forward. A game reinstalled but not replayed can briefly show its install date.
• A Steam launch seems to do nothing: a "Launching via Steam" overlay appears for 25 seconds while Steam takes over, and you can click it to dismiss. Steam itself usually takes the foreground, so you may never see it.

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 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.
6. Leave Pause 3D When in Background on so RetroVoid stops rendering, and stops animating cover art, while you're using another app.

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 upgrades run automatically on startup. Before applying one, RetroVoid writes a retrovoid.db.backup-vN snapshot next to the database and keeps the three most recent backups, so you can fall back to one by renaming it to retrovoid.db.

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

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

Getting Help#

Still stuck? Start with Settings > Guide inside the app, which carries these same documentation pages offline. Then 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, shown under About in the Quick Settings panel (press F1)