Troubleshoot
Quick checks for “won’t open”. Keys, firmware, and games: see first-time setup and the emulator readme.
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.
Graphics / performance
Prefer Vulkan with current drivers. Check in-app graphics options and release notes for known regressions.