FAQ

Frequently Asked Questions

Troubleshooting

Q: the mouse cursor when I run amiberry in KMSDRM is small. Why?

A: Because of a bug in SDL3. Set SDL_KMSDRM_ATOMIC=0 in your environment variable to workaround this.

Performance & Graphics

Q: Why am I having performance and/or screen issues when using Wayland?

A: Some versions of SDL prefers X11 by default, even when running on Wayland. You can force the use of Wayland back-end for better performance: Run amiberry with: SDL_VIDEO_DRIVER=kmsdrm,wayland,x11 amiberry Or set it globally in your profile: export SDL_VIDEO_DRIVER=kmsdrm,wayland,x11

Q: Amiberry on Pi4 is slow (30 FPS/Audio Stuttering). What's wrong?

A: If you are connected to a 4K TV, the Pi might be outputting 4k@30Hz. Amiberry syncs to the monitor refresh rate. Fix: Force your Pi to use 1080p@60Hz in /boot/config.txt (or via raspi-config).

Q: My game runs too fast!

A: This is common with some older games on fast CPUs. Fix: Go to the Chipset panel and enable Wait for Blitter.

Q: Input latency seems high on Desktop Linux.

A: Try disabling your desktop Compositor (e.g., in XFCE: "Window Manager Tweaks" -> "Enable display compositing" -> OFF / Uncheck).

Configuration

Q: I have thousands of config files, and the GUI loads slowly.

A: Amiberry scans description fields by default. Disable this to speed up loading: Edit amiberry.conf and set: read_config_descriptions=no

Q: Can I launch CD32 games from .CUE images?

A: Yes.

• GUI: Load the .cue file in the CD drive slot.
• Command Line: amiberry --autoload game.cue
• Note: Do not use an A1200 config; use the CD32 Quickstart mode.

Q: Why is my physical Audio CD not detected on macOS?

A: macOS natively mounts Audio CDs, which locks the drive. Amiberry has a fallback to read the raw character device instead, but the CD must be inserted and recognized by macOS before starting Amiberry for it to be assigned.

Q: Why does attaching a physical hard drive fail on macOS with error = 13?

A: That means macOS denied access to the raw disk device (usually /dev/rdiskN). This prompt only appears for physical raw disks, not for normal .hdf image files. First, unmount the disk from macOS: diskutil unmountDisk /dev/diskN. For unmounted disks, Finder-launched Amiberry will use authopen to automatically prompt you for authorization to access the raw device.

WHDLoad

Q: Questions about the WHDLoad Booter?

A: Please refer to the dedicated WHDLoad Booter FAQ.

Input

Q: Typing 'x' on the keyboard presses Enter?

A: You likely have the "Keyboard as Joystick" option enabled (e.g., CD32 pad mapping). Fix: Go to Input panel and set Port 1 to Mouse, Joystick, or None instead of a Keyboard layout.

Q: I'm using a tiling window manager, and amiberry doesn't behave as it should

A: On sway add this to your config file:

for_window [app_id="(?i)amiberry"] floating enable, border pixel 0
for_window [title="Amiberry GUI"] focus, border none

For Hyprland

windowrule = float, ^(amiberry*|Amiberry*)$

For i3/i3wm

for_window [class="(?i)amiberry"] floating enable
for_window [title="Amiberry GUI"] focus