Welcome to the Troubleshooting Guide for Batocera Unofficial Addons. This guide will help you diagnose and fix common issues when using the unofficial addons.
Some regions—especially parts of South America—may hit strict GitHub rate limits due to shared IP ranges or unstable routing. When this happens, BUA installers or update scripts may show errors like:
API rate limit exceeded
HTTP 403: Forbidden
HTTP 429: Too Many Requests
This Guide shows you how to raise your GitHub limit from 60 requests/hour → 5,000+ requests/hour, without changing any BUA scripts. Everything happens locally on your Batocera system.
The first step in troubleshooting is to check the logs provided at:
/userdata/system/logs
If there is no log available, proceed with manual debugging by launching the application via Xterm or SSH to get real-time output.
To manually run an application and view its output:
cd /userdata/system/add-ons/<AppName>
./Launcher
ports directory:cd /userdata/roms/ports
./<AppName>.sh
This will display any errors or logs directly in the terminal, helping identify issues with dependencies, permissions, or execution.
chmod +x /userdata/system/add-ons/<AppName>/Launcher
chmod +x /userdata/roms/ports/<AppName>.sh
If issues persist, visit the GitHub Issues Page or join the community on the Batocera Unofficial Add-Ons Discord.