Troubleshooting GBAx

Start by identifying the operation that failed. Installing GBAx, discovering files, retrieving covers, launching a game and emulating a scene use different parts of the application. Changing every setting at once makes it harder to determine which part is responsible.

Keep the exact error text and the GBAx version before making changes. For a game-specific issue, record the title, region/revision and whether it also occurs after an ordinary restart without loading a save state. Back up progress before testing changes to save locations or configuration.

Find the right starting point

Installation and startup

Windows: Preview 1 targets Windows 10/11 x64. Extract the entire ZIP to a normal folder, then run GBAx from that folder. A missing DLL can result from launching inside the archive or copying only the executable. Keep the packaged DLLs and resource directories together; do not collect unrelated DLLs from download sites as a substitute for a complete package.

Linux: the published x86_64 AppImage targets Ubuntu 24.04 or a compatible system with glibc 2.39 or newer. Check the executable permission and the exact terminal output. If FUSE is the problem, test the documented extract-and-run mode:

chmod +x GBAx-2.0.0-linux-x86_64.AppImage
APPIMAGE_EXTRACT_AND_RUN=1 ./GBAx-2.0.0-linux-x86_64.AppImage

An older glibc error is a compatibility-baseline problem, not a ROM setting. The AppImage format does not make every system library independent of the host.

macOS: choose the Apple Silicon or Intel package for your Mac and check the macOS 15+ baseline. Copy the application from the DMG to Applications before testing. Preview 1 is ad-hoc signed rather than Developer ID signed and notarized, so macOS can block it or display a security warning. Report the exact message and package name; an architecture error and a signing-policy message need different investigation.

The library is empty or a game disappears

Open Settings and verify the ROM folder. If files are in nested folders, enable subfolder scanning and run Scan Library. Start with one extracted .gba file in a folder you can read. This separates folder discovery from archive handling and catalogue matching.

The active scan checks supported extensions, excludes symbolic links and inspects ZIP/7z files for supported contents. A compressed collection containing unexpected files may behave differently from a single extracted ROM. Moving a game after scanning leaves an old path in existing selections until the library is refreshed. Reconnect removable drives and network locations before testing a missing file.

A catalogue entry is not proof of an installed game. Conversely, a missing cover does not prevent a valid local ROM from being discovered. See how the launcher scans and indexes files for the underlying process.

Artwork is missing or incorrect

Check Automatically download missing artwork and try Download Missing Artwork. Artwork runs in the background and has its own network requests and caches. Let a small test complete before repeating the command. Use Open Artwork Folder to distinguish a missing downloaded image from a display/cache problem.

Changing the ROM filename can affect title matching. Preserve your original game file and avoid renaming a whole collection to troubleshoot one cover. A screenshot of the title, file name and selected artwork is usually more useful than sending the ROM itself.

Controls, graphics and sound

Test the launcher and game window separately. If a controller moves around the library but a game receives the wrong button, inspect the emulator’s button mapping. If neither responds, check device detection and focus first. Reconnecting a controller can change the device identity the frontend sees.

For visual problems, describe whether the entire image fails to display, the window scales incorrectly, or a particular sprite/background is wrong. A scaling issue belongs to a different path from the software renderer’s composition of a scanline. Keep the same scene and change one relevant setting at a time.

For crackling or missing sound, check mute/volume, the selected audio device and whether the problem changes with background system load. Record any buffer or synchronisation setting you change. Performance Mode reduces launcher visual effects; it is not a general fix for emulated audio or game timing. The audio article explains the difference between producing samples and delivering them to the host device.

Progress does not appear after restarting

First distinguish a normal in-game save from a save state. Confirm the same game revision, file identity and save location are being used. If the game is on read-only or removable storage, check where GBAx is configured to write progress. Stop and copy any existing save files before trying imports or changing paths.

Do not overwrite your only state while investigating a failed load. Preserve the original file, test a copy, and note the emulator version that created it. The save and backup guide explains why states can depend on internal core versions even when normal cartridge saves remain usable.

Use cache clearing and reset for the right problem

Clear Launcher Cache rebuilds generated thumbnails and temporary launcher data. Its confirmation states that downloaded/custom artwork, ROMs, favourites, saves and settings are kept. It is useful when generated launcher data is stale; it does not repair a corrupted game file or change hardware emulation.

Reset GBAx (Clean Start) closes the application, resets settings and the library index, then reopens first-run setup. Its confirmation states that ROMs, saves, artwork and other files are kept. Close a running game first. Use it when you want to rebuild configuration deliberately, after recording your current settings and backing up progress.

For website playback, use the browser troubleshooting steps instead. Desktop launcher resets do not clear or repair browser storage.

Write a report someone can reproduce

Use the project’s issue tracker and include a short sequence that another person can repeat. If you can reproduce without a save state, say so. If a state is essential, record which version created it. Remove personal paths or account information from logs and screenshots before sharing them.

GBAx version / release:
Operating system and architecture:
Package filename:
Game title, region and revision:
Where it happens: launcher / game window / browser
Steps to reproduce:
1.
2.
Expected result:
Actual result and exact error:
Settings changed from defaults:
Does it happen after a fresh launch without a save state?
Screenshots or relevant log excerpt:

A focused report with a repeatable trigger is much easier to investigate than “it does not work”. You can open or search GBAx issues on GitHub to check whether the same symptom has already been reported.