Troubleshoot
Quick checks for “won’t open”. Keys, firmware, and games: see first-time setup and the emulator readme. Odd FPS or visuals after the app runs: see Rendering, FPS, and GPU differences below.
App will not start (Windows)
- Install the latest Visual C++ Redistributable (x64) if the error mentions a missing MSVC runtime (Microsoft).
- Update GPU drivers and ensure Vulkan is available — Citron is Vulkan-focused.
- Allow the app in Windows Security if quarantined.
- SmartScreen: More info → Run anyway (files from GitHub Assets only).
Broke after an update
On CI or emulator releases, open an older entry, re-download the same platform asset. When a build runs, use the in-app menu to open the user data folder and back it up before replacing the binary.
Wrong asset
x86_64 and aarch64 differ; Windows MSVC vs Clang zips differ only by toolchain. Re-download a matching asset. Install steps.
Linux / SteamOS
- AppImage will not run:
chmod +xthe file or enable “execute” in file properties. - Steam Deck: use the x86_64 Linux build, not aarch64. See Linux → Steam Deck.
- Won’t start after an old install: back up and rename the portable
userfolder (or profile path from the readme), launch again for a clean tree, then repeat first-time setup. - GitHub rate limit or API errors: open CI / emulator directly; the site’s direct links use the GitHub API and may fail if the API is throttled.
- Game Mode (Deck) — Apply/OK not clickable: open the Steam keyboard (Steam + X), use Tab to focus Apply, then OK. See also Setup → Steam Deck.
- If the on-screen keyboard stops appearing after sleep, a full restart of the device sometimes clears it.
Rendering, FPS, and GPU differences
- Frame rate and visuals depend on the game, scene (camera, effects), GPU vendor, and driver branch. Promo screenshots usually reflect one tested machine — yours may differ.
- When release notes or tracked issues mention a known quirk for a specific GPU or driver, treat that as authoritative over informal videos or forum posts.
- General checks: update GPU drivers; confirm Vulkan works; if problems began after a driver or OS update, try the previous driver branch; stay on the same emulator build while comparing.
- Reporting a bug: include exact asset filename, GPU model, driver version, and whether it reproduces on the latest tagged release or nightly.