This page collects common checks and links for diagnosing issues. If you do not find your answer here, see the FAQ.

• Review the FAQ performance entries first.
• Check CPU and chipset settings in CPU and Chipset.
• If you use RTG, confirm the configuration in RTG.
• Try disabling JIT for compatibility testing or enabling it for speed, depending on the title.
• On low-power devices, reduce display features (scanlines, high resolutions) in Display.

• ARM64 JIT is supported on macOS (Apple Silicon), Linux (AArch64), and Android (AArch64).
• Current ARM64 JIT builds include safety guards for known unstable startup blocks.
• If a Workbench app/game hangs only with JIT enabled, test with JIT off first to confirm scope.
• Use these environment variables only for diagnostics:
  • AMIBERRY_ARM64_GUARD_VERBOSE=1 enables detailed guard-learning logs.
  • AMIBERRY_ARM64_DISABLE_HOTSPOT_GUARD=1 disables optional hotspot logic, but does not bypass the fixed safety guard for known-bad startup range.

• JIT code memory uses RWX (read-write-execute) anonymous mappings. If SELinux denies PROT_EXEC, a diagnostic hint is logged.
• On Android, run adb logcat | grep -E 'amiberry|JIT|SELinux|avc' to check for JIT-related issues.

• Wayland can introduce additional latency on some setups. If possible, compare behavior on Xorg.
• Ensure vsync and compositor settings are not forcing high latency.
• If you use fractional scaling in the desktop environment, test with it disabled.

• Verify output device and buffer settings in Sound.
• Try increasing default_sound_buffer if you hear crackling.
• If using Bluetooth audio, try a wired output device for testing.
• Disable audio enhancements in the OS audio control panel if present.

• Increase audio buffer size in Sound.
• Reduce CPU‑heavy options (e.g., high resolutions or scanlines).

• Confirm the selected output device in Sound.
• Check that the system mixer is not muted and the device is the active default.

• Confirm device selection and mappings in Input.
• For controller mappings, review Setting up Input Controllers and Custom Events.
• For keyboard-as-joystick, see Setting up Keyboard Controllers.

• Try disabling vsync or compositor settings.
• Reduce frame pacing overhead by lowering scaling or resolution.
• On desktop Linux, test both Wayland and Xorg if available.

• Verify the controller is visible to the OS.
• On Linux, check gamecontrollerdb.txt is present under controllers and Rescan Paths in Paths.
• Try unplugging/replugging the controller and restarting Amiberry.

• Ensure the correct RetroArch .cfg file is selected in Paths.
• Re-run Rescan Paths after updating controller configs.

• Ensure ROMs are in the configured Kickstarts directory and detected by checksum.
• See Kickstart ROMs (BIOS) and ROM Panel.

• Verify the ROM file is not zipped and has a correct checksum.
• Re-run Rescan Paths in the Paths panel.
• Make sure the ROM directory casing matches your OS (see Paths and Files).

• Verify your WHDLoad archive is recognized and mapped.
• See WHDLoad Auto-booting, WHDLoad Booter FAQ, and WHDLoad Panel.

• Confirm the .lha is recognized in the WHDLoad database.
• Ensure WHDLoad boot files are present in the whdboot directory.
• Check that the WHDLoad archive is in the configured WHDLoad path.

• Save states have known limitations with some devices and settings.
• See Savestates for compatibility notes.

• Try launching the associated .uae config first, then load the state.
• Avoid JIT for save states if you encounter crashes.
• Make sure the original game files are still in the same location.

• Temporarily move amiberry.conf aside to allow a fresh one to be generated.
• Check the log file for errors (amiberry.log).
• If using -G or use_gui=no, remove those to verify the GUI appears.

• Try a different default model in Quickstart.
• Ensure a valid Kickstart ROM is selected in ROM.
• Disable RTG temporarily and test with native display modes.

• macOS mounts Audio CDs via cddafs which locks the drive. Amiberry uses a fallback to read the raw character filesystem.
• Make sure the CD is inserted and spun up in macOS before you launch the emulator so DiskArbitration can map it.

• If the log shows HDF '/dev/rdiskN' failed to open. error = 13, macOS denied raw device access.
• First unmount the whole disk: diskutil unmountDisk /dev/diskN
• After the disk is unmounted, Amiberry will use authopen to automatically display a macOS authorization dialog requesting read/write access to the raw disk device.
• If you cancel the authorization dialog, the disk will not be attached. Simply try again from the GUI by selecting the physical disk again — the authorization prompt will reappear.
• Prefer mounting a disk image (.hdf, .img) over a live physical device when possible.
• See also HDD Panel.

• Confirm directory locations in Amiberry Directories.
• Review the log file (amiberry.log) in your configured HOME path.