Something is not working? This page gives the first reflexes, the solutions to the most common issues, and the right way to ask for help.
SELECT → RESTART RECALBOX on the system list): it solves more cases than you would think.All logs live in share/system/logs, directly reachable through the \\RECALBOX\logs network share (see File management).
| File | Contents |
|---|---|
frontend.log |
The interface (EmulationStation) journal — including the backtrace of a possible crash. Previous boots are in frontend.backup*. |
es_launch_stdout.log / es_launch_stderr.log |
Everything that happened when the last game was launched: the first reflex when a game does not start or closes immediately. Overwritten at each launch. |
recalbox.log |
Messages from the system scripts (boot, storage, network…). |
web-server.log |
The web manager journal. |
For more verbose logs: START → ADVANCED SETTINGS → ACTIVATE DEBUG/VERBOSE LOGS, then reproduce the problem.
The support archive gathers in a single file everything the team needs to help you: version, configuration, logs, detected hardware, controllers… Sensitive data (Wi-Fi keys, account passwords) is automatically masked.
http://recalbox.local in a browser): the round button at the bottom right unfolds the actions menu → Support archive. The archive is generated then downloaded by your browser./recalbox/scripts/recalbox-support.sh — the archive path is printed.In both cases the archive (recalbox-support-<date>.tar.gz) is dropped in the share/saves folder. It is the file to attach when you ask for help.
Reconfigure it: START → CONTROLLER SETTINGS → CONFIGURE A CONTROLLER. Since 10.1 the wizard is visual — follow the guide Configure a controller.
es_launch_stderr.log right after the attempt.START → BIOS CHECKING — see Bios check._readme.txt in the system's rom folder lists the accepted extensions.PS button.If it seems completely dead, reset it: a small button hides in a hole on the back of the controller (reachable with a paper clip).
Adjust your TV first: look in its picture menu for the "1:1", "Full" or "Fit to screen" size option (TV overscan is the number one cause). To go further: the video tutorials.
system.ssh.enabled=1), user root, password recalboxroot — see Root access.F4 quits the interface, then ALT + F2 opens a terminal. Type es start (or reboot) to get the interface back.Support happens on Discord: the community and the team answer every day. For a quick answer, provide right away:
START → SYSTEM SETTINGS);Recalbox 9.x and earlier are no longer supported: start by updating or reinstalling to 10.1.
Your settings vanished on their own, and your case's shutdown script no longer responds? An automatic protection kicked in.
Recalbox counts the boots that do not complete. On the seventh in a row, it assumes a system modification is preventing startup and puts that system back to new: the overlay folder is set aside and the case configuration is disabled. The counter resets as soon as a boot completes — so it takes seven consecutive failures to get there.
What you lose: the system changes you made outside the SHARE partition — hand-installed packages, files edited under /etc, scripts added at startup. Your games, saves, bios and your recalbox.conf are not affected: they live on SHARE.
What can be recovered: the previous content is left in /overlay/upper.old, reachable over SSH.
That backup does not survive a second cleanup: the previous
upper.oldis erased before being replaced. If this happens twice, whatever you had the first time is gone for good.
The case: if you use a case with managed shutdown (Argon, NESPi, SuperPi…), its configuration is removed at the same time. Follow your case's procedure again to re-enable it.
Why it triggered: because seven boots in a row did not complete. A power supply problem, a worn SD card or repeated power cuts produce the same effect as a faulty system change.
You copy games, you configure things, and everything is back to square one at the next boot? The configured storage could not be mounted, and Recalbox fell back to a RAM disk.
This is an automatic fallback: rather than refusing to boot, Recalbox mounts a temporary 128 MB space in place of the share. The interface works normally, but nothing is written to a physical medium — everything is lost at shutdown.
To check, over SSH:
mount | grep /recalbox/share
If the line starts with tmpfs, that is what happened. A healthy install shows the real device (/dev/mmcblk0p2, /dev/sda1…).
Usual causes: an SD card at end of life or badly seated, a corrupted SHARE partition, or an external device missing while the share was configured on it. The file manager and the network share still work, which makes the failure all the more confusing: copied files appear to arrive, then evaporate.
Stop copying anything until the mount is fixed: whatever you transfer is lost, large downloads included.