mGBA Logo mGBA

Troubleshooting Guide

This guide provides solutions to common issues and problems encountered when using mGBA. If you encounter a problem not covered here, please check the FAQ section or report the issue on GitHub.

Common Issues and Solutions

Game Won't Load or ROM Not Loading

Problem:

Game ROM file won't load or mGBA doesn't recognize the file.

Solutions:

  1. Verify the ROM file is a valid Game Boy Advance ROM (.gba format)
  2. Check if the file is corrupted - try re-downloading if possible
  3. If the ROM is in a ZIP archive, extract it first
  4. Ensure the ROM file isn't damaged or incomplete
  5. Try loading a different ROM to verify mGBA is working
  6. Check file permissions (ensure mGBA can read the file)

Low FPS or Performance Issues

Problem:

Game runs slowly or frames are skipping.

Solutions:

  1. Enable hardware acceleration (OpenGL, Vulkan, Direct3D 11, or Metal)
  2. Reduce resolution scaling (try 1x or 2x instead of higher scaling)
  3. Enable automatic frame skipping
  4. Close other resource-intensive applications
  5. Update graphics drivers to latest version
  6. Check if your hardware meets minimum requirements
  7. Try different rendering backends (software if hardware fails)

Audio Stuttering or Cracking

Problem:

Audio is stuttering, crackling, or skipping during gameplay.

Solutions:

  1. Increase audio buffer size in Settings β†’ Audio
  2. Reduce sample rate (try 32 kHz if 44.1 kHz causes issues)
  3. Disable frame skipping if enabled
  4. Close other audio applications
  5. Check audio drivers are up to date
  6. Try different audio backends
  7. Reduce CPU usage from other applications

Save Files Not Working

Problem:

Game saves are not persisting or save files are not being created.

Solutions:

  1. Ensure mGBA has write permissions in its directory
  2. Run mGBA with administrator privileges if needed (Windows)
  3. Verify ROM and save file names match exactly
  4. Check save directory is not read-only
  5. Check available disk space (low disk space may prevent saving)
  6. Verify save type detection is correct (EEPROM, Flash, SRAM)
  7. Manually set save type if auto-detection fails

Graphics Glitches or Visual Artifacts

Problem:

Graphics are corrupted, glitchy, or displaying incorrectly.

Solutions:

  1. Switch between different rendering backends (OpenGL, Vulkan, Direct3D, Metal)
  2. Disable VSync if it causes issues
  3. Update graphics drivers to latest version
  4. Try software rendering if hardware acceleration causes problems
  5. Disable custom shaders or filters
  6. Reset video settings to defaults
  7. Check if specific game has known compatibility issues

Gamepad or Controller Not Working

Problem:

Gamepad or controller is not detected or controls don't work.

Solutions:

  1. Connect gamepad before launching mGBA
  2. Go to Settings β†’ Input β†’ Gamepad to configure
  3. Click each button to remap controls
  4. Restart mGBA with controller connected
  5. Check if gamepad is recognized by your operating system
  6. Try different USB ports (for USB controllers)
  7. Update gamepad drivers
  8. Test gamepad with other applications to verify it works

Link Cable Emulation Not Working

Problem:

Multiplayer or link cable emulation is not connecting.

Solutions:

  1. Enable link cable emulation in Tools β†’ Link Cable before loading games
  2. Ensure both instances have the same game loaded
  3. Check firewall settings if using network mode
  4. Verify both instances are on the same network (local network mode)
  5. Check IP address configuration for network connections
  6. Try restarting both mGBA instances
  7. Ensure the game supports link cable multiplayer

Cheat Codes Not Working

Problem:

Cheat codes are not taking effect or causing crashes.

Solutions:

  1. Verify cheat code format matches the game version
  2. Check if cheat codes are for the correct game and region
  3. Ensure cheat codes are enabled (check checkbox)
  4. Try loading cheat codes before starting the game
  5. Verify cheat code format (GameShark, Action Replay, CodeBreaker)
  6. Some cheats may require specific game states to work

mGBA Crashes or Freezes

Problem:

mGBA crashes, freezes, or becomes unresponsive.

Solutions:

  1. Update to latest version of mGBA
  2. Update graphics drivers
  3. Check system logs for error messages
  4. Disable custom shaders or filters
  5. Reset configuration to defaults
  6. Check available memory (low RAM may cause crashes)
  7. Verify ROM file is not corrupted
  8. Report crash with error details on GitHub Issues

Platform-Specific Issues

Windows

  • Visual C++ Runtime Error: Install Visual C++ Redistributable
  • DirectX Errors: Update DirectX runtime libraries
  • Permission Errors: Run as administrator or adjust folder permissions
  • Antivirus Blocking: Add mGBA to antivirus whitelist

macOS

  • "App is Damaged" Error: Remove quarantine attribute: xattr -d com.apple.quarantine mGBA.app
  • Gatekeeper Warning: Allow app in System Preferences β†’ Security
  • Metal Errors: Update to latest macOS version

Linux

  • Missing Libraries: Install required dependencies (SDL2, Qt5, etc.)
  • Permission Errors: Check file permissions and ownership
  • Graphics Issues: Update Mesa drivers or proprietary GPU drivers

Getting Help

If you cannot resolve your issue:

  • Check the FAQ section on the main website
  • Search existing GitHub Issues for similar problems
  • Create a new GitHub Issue with:
    • Detailed description of the problem
    • Steps to reproduce the issue
    • Your system specifications (OS, CPU, GPU)
    • mGBA version
    • Error messages or logs if available

Related Articles

For more information about mGBA configuration and usage: