Troubleshooting

Troubleshooting

"Cannot connect to RomM"

• Check that your RomM server is running and reachable
• Verify the URL includes the correct port (e.g. http://192.168.1.100:8285)
• If using Tailscale, make sure both devices are on the same tailnet
• Try accessing the RomM web UI from a browser on the same device first
• If using HTTPS, check your certificate is valid

"Authentication error / session expired"

• Freegosy silently re-authenticates using stored credentials
• If this keeps happening, switch to API Key auth (more stable)
• Go to RomM Settings → Client API Tokens → Generate new token → paste into Freegosy Settings

"Emulator not found"

• Download the emulator from Settings → Emulators
• If already installed, the executable may have been moved or renamed
• On macOS, ensure the .app bundle is in the Freegosy emulators directory (not Applications)

"Ares not found" or "Ares does not support platform"

• Ares supports: GBA, GBC, GB, SNES, N64, Genesis, PS1, MSX, and more (30 platforms)
• Download Ares from Settings → Emulators
• If you see "does not support platform", the game's platform slug is not in Ares's supported list — use a different emulator for that platform

"Missing RetroArch core"

• The error message shows the exact core filename and expected path
• Freegosy will attempt to download the core automatically on the next launch attempt
• You can manually place the core .dll (Windows) or .dylib (macOS) in {retroarch}/cores/

"Save sync: Save directory not found"

• Launch the game at least once in the emulator to create the save directory
• Then retry the sync

"Save sync: Save mapping required" (Eden / Azahar)

• This appears when Freegosy cannot automatically determine the Title ID / save folder
• A folder picker dialog will appear showing available save folders
• Select the correct one — Freegosy will remember it for future syncs
• For Eden: folders are named as 16-character hex Title IDs (e.g. 0100704000B3A000)
• For Azahar: folders are in the sdmc directory

"Game crashed immediately (Windows native)"

• Usually means missing Visual C++ redistributables or DirectX
• Install the latest VC++ redist from Microsoft
• Install DirectX End-User Runtime

macOS: App won't open / "damaged" error

• Run in Terminal: xattr -rd com.apple.quarantine /path/to/Freegosy.app
• Or right-click the app → Open → Open anyway

RomM 4.8.x: Personal game properties not saving

• Known RomM server-side bug in 4.8.0 where PUT /api/roms/{id}/props returns 200 but doesn't persist
• Workaround: update RomM to a newer version if available, or wait for upstream fix
• Freegosy correctly sends the request; the issue is server-side

Controller not recognized or wrong buttons

• Freegosy supports: Xbox, PlayStation (DualShock 4, DualSense, PS4/PS5 USB), Switch Pro, 8BitDo, Logitech, and generic USB controllers
• PlayStation USB on Windows: recognized as "PS4 Controller" or "PS5 Controller"
• PlayStation on macOS/Linux: recognized as "Sony Interactive Entertainment Wireless Controller"
• Unknown Bluetooth controllers may get default mapping — check Settings → Controllers to verify
• Custom mappings can be saved per controller via the settings UI

Windows game: "No executable found"

• Freegosy searches for .exe, .bat, and .cmd files in the game folder
• It skips redistributables (vcredist, setup, uninstall) and macOS metadata folders (__MACOSX)
• Use Game Detail → Configure to manually set the executable path
• Launch arguments can be set in the same dialog if the game needs specific flags