Report an Issue (with the highest chance of it being fixed)

Recommended reading:

So, you've found an issue with Batocera. A true, genuine bug with the way Batocera functions. You've gone through the troubleshooting page and confirmed it's not a misconfiguration, you've gotten other operating systems running fine on the machine so it's not a hardware fault and you've tested the ROMs and BIOS files with another emulator on another system where they work fine. Or maybe things were working fine in a previous version, and in a newer version they do not, and you've tested downgrading to see that the issue is indeed not present on the older version (this is referred to as a regression).

And now you want to report that bug.

Here's a guide on how to report a bug and giving the highest chances of it being actually fixed by the next major release of Batocera. Batocera is a very complicated project, and it's only by the efforts of multiple contributors that it can be made and released for so many platforms. Usually, devices are worked on by the individuals who have those devices for testing and have the technical know-how on how to implement it, so not all devs have access to all devices at all times. In essence, don't expect a dev to reply to you quickly, especially if you're on a platform that's “less common” like an SBC. Remember, Batocera is entirely a volunteer project, we all work on this in our spare time.

First, check that there isn't already a duplicate issue on the batocera.linux or batocera-emulationstation Github issues page which you could contribute your information to instead. After you've made certain your issue is unique, submit it using the formal report format as specified below to a new “issue” to the respective repository's issues page (you may need to create a Github account to do this).

Although you can also report issues on our Discord server, these are likely to be missed by our devs as we receive hundreds of messages per day on there!

Although other projects may utilize Github issue reports for a variety of things such as feature requests or implementation/PR assistance, Batocera only uses the issues page for bugs/genuine issues with Batocera.

Here is a list of things you should not use the issues page for and the alternative location for them:

  • Feature requests should instead be put in the #batocera-linux-requests channel on the Discord server.
  • Implementation/PR assistance (for developing Batocera) should instead be guided towards the #developers and #developers-emulationstation channel on the Discord.
  • Issues specific to the emulator and the game it is running. Usually they should be reported to the dev of the emulator itself, as it is outside of the scope of Batocera. This includes things such as “weird geometry corruption in my Dreamcast game!” and “textures look weird on my PS2 game in PCSX2 but not Libretro/PCSX2”. These emulators usually have their own documentation/wiki that you can check for and troubleshoot with instead first, it is recommended to do your research.
  • Issues specific to EmulationStation (Batocera's front-end, the “main menu” essentially) should go to the Github issue page specific to it instead. This includes things such as images appearing as white squares, text corrections, menu functions not behaving as intended, etc.

This is the current stable versions available to download from the main website. This is not the beta.

Ensure that you have checked for the following first:

For a major issue such as Batocera completely crashing or becoming unresponsive (soft-lock), try reflashing the Batocera image from scratch and try again. If the issue is then no longer present, piece your setup together piece by piece, testing between each addition, until you find the causation of the issue. Then you can provide that information as a part of your formal report. If your issue is still present on a fresh install, then continue on to the process of making a formal report.

Here's an example of a bug report that will likely not get investigated:

Sega Model 2 emulation isn't working please fix!

Although the user has specified the particular system, there has been no information actually provided here. Despite being rude, a dev might still look into it, but they'd find that the emulator is launching fine and probably leave it as a non-issue. There are many cases of “emulator not launching” actually being user error, and easily repairable if they had followed the troubleshooting guide.

Here's a slightly better, but still unlikely to be fixed issue report:

The standalone Sega Model 2 emulator isn't working. I'm on Batocera v32 beta on a PC and set up all my ROMs, BIOS, etc. correctly.

This seems like it provides enough information, but in reality it doesn't provide anything meaningful, and will still likely not be fixed or investigated. This is because no actual relevant information has been provided: there are no logs, no feedback on why it fails, no results or method to reproduce, no platform specification (is this x86, x86_64, a handheld PC or a USFF?), etc. This is also usually another case of user error, even though the user claims to have “set up all my ROMs, BIOS, etc. correctly”, they have not provided the specifics of how they have done so (such as “I put my game into the /userdata/roms/sega/ folder as per the instructions on the wiki”) nor the logs associated with the emulator not launching.

This user is also on the beta build of Batocera. When reporting for issues, it is recommended to do so on the current stable build, as that's the least likely to have any major bugs in it that could dramatically affect other aspects of Batocera. The only time you should report an issue while using a beta build is if you are explicitly beta testing for Batocera.

Here's how to provide a report with the highest chance of being fixed:

Issues should be reported with the following format to the Batocera Github issue page to give them the greatest chance of being fixed (erase the placeholder text and put in your own):

Issue: A laconic explanation of the issue, including your platform and version of Batocera. Keep this to a single sentence.

Expected result: What the intended behavior should have been instead.

Reproduction steps: 1. Note the steps in the order they are required to be done in order to successfully reproduce this issue.

2. Include any “but only when” conditions you have discovered.

3. Describe what happens when the issue occurs, anything to look out for, anything to check the issue has indeed occurred.

Logs and data: Provide all the relevant logs and information relevant to the issue. Include any information about the platform you are on, the hardware being used (most applicable for x86 and x86_64 platforms), the stable versions of Batocera the issue is present/not present on, whether the issue is present on a fresh install or not, etc.

If you are not certain which logs are relevant or the logs you do have don't describe the issue, create a support file instead. Do note that this file can contain the following personal information:

  • Your IP address is in system/ifconfig.txt, system/messages and system/netstat.txt
  • Your Wi-Fi SSID and password is in system/batocera.conf and system/batocera-boot.conf
  • Your RetroAchievements username and password are in system/batocera.conf, configs/retroarch/retroarchcustom.cfg and any configuration override files if you've made them
  • Your scraper API account is in system/es_settings.cfg and configs/emulationstation/es_settings.cfg
  • Your NAS login details are in system/batocera-boot.conf

Be sure to either scrub it first if the issue isn't relevant to that information or just use a temporary password to be changed after the report.

Example of a good report

Hardware issue

Issue: I can't get audio out of my RPi 4 on Batocera v32.

Expected result: To be able to hear sound from my HDMI output.

Reproduction steps: 1. Flash Batocera on the SD card.

2. No audio is output from HDMI. No option for HDMI exists in the audio output settings or profile.

Logs and data: I flashed Batocera v32 onto my RPi 4 but found that there is no HDMI option in the audio output settings either. There's no sound on my splash screen, in emulators, or even Kodi. With Batocera v31 everything is working out of the box.

Here is my Batocera v32 support file: <uploaded zip of support files>

Emulator issue

Issue: The Sega Model 2 emulator on x86_64 is crashing on launch of any games on Batocera v32. Attempting to launch the game soft-locks Batocera (no response to any controller input, have to hard-reset).

Expected result: To be able to launch known-working games without crashing, just like it can on Windows/other Linux distribution.

Reproduction steps: Flash Batocera v32 onto the drive and setup the ZIP ROMs into /userdata/roms/model2/ and ZIP BIOS files into /userdata/bios/ as per the instructions on the wiki:

Logs and data: After crashing and rebooting I found the ES logs in /userdata/system/logs here: <attached stderr.log and stdout.err>. I noticed it says “ERROR: segmentation fault” in there, whereas this line does not appear on the same stderr.log on my other Linux distribution.

The purpose of the betas are to (hopefully) catch major bugs and fix them before going into release candidate/major release stage.

A timeline of when certain changes are allowed to be merged upstream can be found here:

A list of platforms Batocera is currently available on can be found here:

These are for major issues noticed with the beta leading up to its conversion into a release candidate. A dev will usually create a post on the general topic of the forum (such as this one for v32 beta) where this thread is temporarily monitored. This is where major issues can be reported such as particular emulators failing to launch, certain platforms consistently crashing, etc.

This format of bug reporting is usually quicker and more responsive, hence an as-large detailed report is (usually) not required. Try to give as much detail as possible while being succinct, people don't like having to scroll through wads of text. If you're finding it too difficult to cram all the relevant information into one or two paragraphs, consider making it a formal issue report instead and link to it from the thread.

Leading up to the major stable release date, a release candidate based on the beta will be made. A dev will usually create another topic in similar fashion to the beta (such as this one for v32 rc). At this point, less significant changes can be made to the codebase (such as driver versions being frozen, etc.) but minor bugfixes can still be implemented. This is for smaller, more isolated issues such as a new particular feature not working as intended, the scraper API breaking, playlist generation not functioning, crazy default settings, etc. Try to find the file related to your issue as well, and if you're handy with overlays, see if you can test fixing it yourself.

If you're finding it too difficult to be succinct with your issue, then it's possible that this is a bug that cannot be fixed by the next major version. This can be disheartening, but when this happens your best course of action is to wait until the next stable releases, test its behavior there, and then make a formal report about it (as mentioned above).

  • report_issue.txt
  • Last modified: 4 months ago
  • by maximumentropy