This version is outdated by a newer approved version.DiffThis version (2021/10/15 02:36) is a draft.
Approvals: 0/1

This is an old revision of the document!


System Troubleshooting

If trying to use HDMI sound on a Radeon GPU, first check that you have enabled the setting in the boot line. If on a Nvidia card, make sure your official drivers are activated.

When that's all clear, first experiment with different settings in MAIN MENUSYSTEM SETTINGSAUDIO PROFILE. You should get sound immediately when exiting back to the MAIN MENU (there is background music playing by default). If you're still not able to get any sound, try also manually setting an AUDIO OUTPUT device (they change with each different profile, you need to exit back to MAIN MENU to update the list). To rigidly test all your hardware's possible audio output modes (this may take a lot of trial and error, but only needs to be done once):

  1. Go to MAIN MENUSYSTEM SETTINGSAUDIO PROFILE and select the first profile, then back out to the MAIN MENU.
  2. Go back into SYSTEM SETTINGSAUDIO OUTPUT and test all available outputs, exiting to the MAIN MENU between each change.
  3. If none of the AUDIO OUTPUT options worked, repeat steps 1-2 for a different AUDIO PROFILE. Your AUDIO OUTPUT options might change depending on the AUDIO PROFILE selected.

Batocera v32 reworked the way it handles audio, so most issues are now resolved by simply selecting the right device and profile in the settings menu. If you're still having issues or are using an older version of Batocera, audio issues is on its own page.

Perhaps the Trash folder still has your files stored on the drive? You can clear these out by going to the file manager ([F1] on the system list), clicking Trash Can and clearing it out.

If you've already done that and still get the error, it could be that Trash Can has failed to actually removed the files. If so, you can forcefully remove the files by navigating to /userdata/system/.local/share/Trash/files, selecting everything and pressing [Shift]+[Del] to delete all the contents. You can also do this via SSH by running rm -rf /userdata/system/.local/share/trash/. The rm -rf /path/to/somewhere command is capable of destroying your hard-drive, so be very careful with your spelling on this.

If you'd like to avoid this issue in the future you can tell the file manager to not use your trash folder and default to instantly deleting files. Click on Edit in the menu bar located at the top of the screen in the file manager, then go to Preferences and uncheck the “Move deleted files to “trash can” instead of erasing from disk” checkbox. Click Close to save the setting. Files that are deleted via the network share aren't sent to the trash can.

When an emulator fails to launch, you will be immediately returned to the game list in EmulationStation. Most of the time when this happens, you will find some useful information in /userdata/system/logs/es_launch_stderr.log and /userdata/system/logs/es_launch_stdout.log (also known as \\BATOCERA\share\system\logs\es_launch_stderr.log and \\BATOCERA\share\system\logs\es_launch_stdout.log from the network shared drive).

Come to the Discord channel with this file, and you'll usually get some pointers as to what's wrong. In many cases, you can see problems with the BIOS missing, bad ROM format, etc.

  • If you are using any custom scripts in /userdata/system/scripts/, try removing them first (or renaming the scripts/ folder to backupscripts/ to temporarily disable them).
  • If you are using any custom es_systems.cfg, try removing/resetting that first. This includes anything you may have set with custom overlays.
  • Your storage medium (read: cheap USB stick) might be too slow to be usable. This is rare, but certain USB sticks can't transfer at a rate faster than 1 MB/s, which could be a problem. This is irrelevant of what “type” of USB version it supports, there can still be crummy USB 3.0 sticks. Try again by first plugging the drive into another port, and if it still persists try with Batocera flashed to another USB stick/storage medium. Sandisk and Samsung USB sticks are typically reliable.
  • For weaker SBCs, you can also try turning on interface preloading in SYSTEM SETTINGSDEVELOPERINTERFACE PRELOADING. You can also try disabling the game preview from showing with HIDE WHEN RUNNING A GAME in that same submenu.

It could be that you're using an extremely slow USB drive (like 1.0, though all of those are likely to have already died due to their age), have a faulty SD card, or if using a USB connected portable drive are using an cheap SATA-to-USB cable which does not support the USB Attached SCSI protocol driver (UAS).

If the latter, you can check what driver has been loaded to use your USB with the lsusb -t command. It will output something like so:

[root@BATOCERA /userdata/system]# lsusb -t
...
/:  Bus 02.Port 1: Dev 1, Class=root_hub, Driver=xhci_hcd/6p, 5000M
    |__ Port 2: Dev 3, If 0, Class=Mass Storage, Driver=uas, 5000M
    |__ Port 4: Dev 5, If 0, Class=Mass Storage, Driver=usb-storage, 5000M
...

In this example, device 3 (Driver=uas) is UAS-capable, while device 5 (Driver=usb-storage) is not. If UAS isn't supported by your SATA-to-USB cable, you may experience intermittent access issues with that portable drive.

You can first check for the BIOS settings on the install Batocera page. Then, check for the following:

  • You may need to change your BIOS to allow legacy boot, as some motherboards may only allow Windows to boot on UEFI.
  • If your BIOS is UEFI and you can't use legacy boot, make sure you can load bootx64.efi from Batocera's boot partition.
  • Make sure you have enabled “unsecured boot” option in your BIOS, this is a requirement for most Linux distributions.
  • If also using Windows on the same machine, ensure that Windows isn't hibernating or otherwise holding the system access hostage by some means (fast boot, quick start, etc.)
  • Unplug any other storage devices (such as your internal drive with another OS on it) or controllers.
  • The Batocera image may not have been flashed correctly, try reflashing with Etcher and make sure the validation says “successful”.
    • Some users have reported on Windows that a complete reformat to NTFS is needed for the USB drive before flashing to make Etcher work correctly.
    • Some users have reported that Etcher only works correctly on Windows 10 and newer, though it should work irrelevant of OS used to flash the image.
  • If using a SATA-to-USB cable for a USB hard drive or SSD (all 2.5“ and 5” hard drives use them, even if they hide it in the case), your cable may not support TRIM which is required to properly boot; try a different SATA-to-USB cable or a different drive.
  • Some USB drives (particularly USB 3.0 and above ones) may not be properly read/compatible with your motherboard's chipset, try another drive/port.

By default Batocera will suppress most of the boot related messages during the boot sequence. If you'd instead like to see these to help with diagnosing your boot issue, you can disable the quiet option in the boot parameters.

To do so, edit the following file:

  • For legacy boot: /boot/boot/syslinux/syslinux.cfg (if on Batocera 5.24 or lower, /boot/boot/syslinux.cfg)
  • For EFI/UEFI boot: /boot/EFI/BOOT/syslinux.cfg (if on Batocera 5.24 or lower, /boot/EFI/syslinux.cfg)

and replace the following line:

APPEND label=BATOCERA console=tty3 quiet loglevel=0 vt.global_cursor_default=0

With:

APPEND label=BATOCERA console=tty3 loglevel=9 vt.global_cursor_default=0

The two things that have been changed is the removal of parameter quiet and the increasing of the loglevel from 0 to 9.

Be careful when editing this, as the boot command needs a very specific syntax. Any additional new lines or spaces that your editor might add after pasting could interfere with booting successfully. Make sure to back up the file first just in case!

If accessing Batocera over SSH or through terminal, don't forget you need to put the /boot/ mount point in write mode first.

This is for if you're struggling to even boot on an SBC, which is a rare occurrence (SBCs tend not to be nearly as modular as standard desktop PCs) and usually only caused by hardware faults/external factors. Here are some general troubleshooting steps to try:

  • It could be running undervoltage and failing to boot (the most intensive task for the CPU). First try unplugging any external USB devices you may be using, including external hard-drives, USB mice/keyboard, controllers, Ethernet cable, etc. Ensure that you are using the official recommended power supply for your SBC.
  • Disable any network shares you may be trying to use.
  • Remove your game's metadata (gamelist.xml and the images and videos folders from the roms/<system>/ directory).
  • As a final resort, try re-flashing the SD card. Some users have reported that a complete reformat of the card to a blank state was needed before Batocera would start booting on that card.

Since the graphics drivers aren't loaded at boot the splash video is rendered entirely on the CPU. If you have either 1. an absurdly high resolution display like a 4k TV, 2. a really weak CPU to begin with then this could cause the boot video to lag. You can solve this by forcing the splash video to render at a lower resolution (say 1920×1080 or 1280×720) by editing the configuration file.

splash.video.resize=1280x720

This can be done in either `batocera-boot.conf` or `batocera.conf`.

First check that you have the right video output selected in the system settings. If you're on a laptop, you may need to connect an external monitor to see this (as maybe it defaulted to that instead of the embedded display).

It may also help to activate your Nvidia drivers/Intel drivers if using those applicable devices.

Several video issues on PC x86 and x86_64 can be investigated with xrandr as described on this page.

If you use Batocera with a display that provides a high resolution like a 4K monitor, you might have trouble reading the text on the file manager ([F1] on the system list on PC) or the configuration screens of a few emulators. You can change the default DPI settings by editing batocera.conf and look for the section:

## DPI
## Workaround when correct DPI setting is not detected
## if fonts are too small, uncomment next line
#global.dpi=96

If you can't get access to SSH because the network is not available, on x86/x86_64 you can still access the local xterm command line with a mouse and keyboard.

  1. Navigate to the system list (where you choose your console) and press [F1] to open the file manager.
  2. Click “Applications”, then double-click xterm.

In case you can't access the file manager for whatever reason, you can skip straight to another TTY session with a command line by pressing [Ctrl]+[Alt]+[F5]. You will need to enter your user (root) and password (by default, linux). You can return to Batocera by pressing [Ctrl]+[Alt]+[F2].

In Batocera v31 and below, the shortcut is [Ctrl]+[Alt]+[F3], however this terminal is very buggy (prone to garbling inputs/characters and illegible output) and should only be used in emergency situations.

If it's just not appearing, first of all ensure that your computer and the Batocera machine are connected to the same network (sometimes routers will separate the Wi-Fi and Ethernet networks, but most will combine them internally). Then, you can type \\BATOCERA (under Windows or MacOS) or smb://BATOCERA.local (under Linux) to directly navigate to the Batocera network share. If your router doesn't support hostnames properly (many old routers do not), type in the IP address of the Batocera machine instead of its hostname (for example, \\192.168.1.2). You can find the IP address under MAIN MENUNETWORK SETTINGSIP ADDRESS.

If you are on Windows, it could be the following:

  • Your network area is set to public, which disables local network shares.
    1. Open the Network and Sharing Center (type “network and sharing” in the Start menu and it should appear).
    2. Click on Public/Work network on your active network (there may be more than one if you have multiple connections, select the one you know is actively being used). If it is already on “Home network” then this isn't the issue.
    3. Select Home network in the “Set Network Location” window that appears (of course, don't do this on a public network like McDonalds Wi-Fi).
    4. Try accessing \\BATOCERA again.
  • The network stack just hasn't updated yet.
    1. Open the Network folder in the file explorer.
    2. Click on an item in the network (any other share) and press [F5] to refresh the list. If there are no items, you can click anywhere in the window and this will still work.
    3. Try to connect to the \\BATOCERA network share again.
  • Samba might be disabled on your Windows entirely.
    1. Open the Start menu and search “turn windows features on or off”, click on the identically named entry.
    2. Search for and check SMB file sharing support 1.0, CIFS, SMB1.0, CIFS client, etc.
    3. Reboot Windows and try accessing \\BATOCERA again.

If you are on Windows 10 version 1709 or above specifically on Enterprise, Education or Server 2019 (Datacenter and Standard) editions, access to guest shares is disabled by default. Blame Microsoft (they did it for security reasons though, but that isn't applicable for local home networks). You can refer to this DevAnswers guide for a walkthrough, but here are those instructions summarized:

  1. First, open the cmd.exe (search Start) and run c:\net use \\BATOCERA. If you get “System error 1272 has occurred” then continue with these steps. If something else, it may not be this issue, but you can continue anyway just to be sure.
  2. Press [Win]+[R] and type regedit then press [Enter].
  3. It will ask for administrator privileges, click “OK”.
  4. Press [Ctrl]+[F] and search for AllowInsecureGuestAuth.
  5. When a result is found, double click it and change its value to 1. The first time this is done, it will configure this setting only for the current user.
  6. Repeat steps 3 and 4 one more time. This will set the configuration for both the user and the default user. Repeat again if there are more users. If you only want to set it to the current user, set it only once.
  7. [Ctrl]+[F], uncheck Keys and Data and search for RequireSecuritySignature.
  8. When a result is found, double click it and change its value to 1.
  9. Repeat steps 6 and 7 one more time. This will set the configuration for both the user and the default user. Repeat again if there are more users. If you only want to set it to the current user, set it only once.

This is for if you having trouble connecting to the network via an ethernet cable, which otherwise works fine with Windows. Note if the link LED (the orange one that stays steadily lit, not the yellow one which flashes) turns on when your computer shows you the POST screen (where you press a button to enter BIOS settings) or if until Windows has started booting. If it doesn't turn on until Windows is booting, you may need to disable the 'Shutdown Wake-On-LAN' feature of your Realtek ethernet adapter.

  • Boot into Windows, hit start and type in “device manager”.
  • Navigate to Network Adapters, right click your Realtek Ethernet adapter and go into its properties.
  • Click on the Advanced tab and scroll down to the “Shutdown Wake-On-LAN” property.
  • If it's “Enabled”, set it to “Disabled”. Press OK.
  • Reboot back into Batocera, noting if the link LED turns on at the POST screen.

If that did not do anything, you may need to also activate such a feature within your BIOS settings. This may be referred to as “Onboard LAN Boot ROM”, “Allow waking via LAN ROM” or something similar.

The best advice for this is… don't use Wi-Fi. Use an Ethernet cable, especially if you want to do something ping-sensitive like Netplay or game streaming. In the modern high-tech world we live in there is so much wireless noise in the air that getting a consistent, lag-free Wi-Fi signal is a pipe-dream. Only if you're seated right next to the router less than a few feet away, and even then…

But if your situation absolutely requires the use of Wi-Fi, here are some tips:

  • Turn off as many other Wi-Fi enabled devices as you can, including your phone, your smart thermostat, your fridge, etc.
  • Turn off any large mechanical devices that throw out lots of interference like combustion engines, generators, UPS's, microwaves, etc.
  • Try to have a direct line-of-sight to your router. If that is not possible due to a wall being in the way, try to have the least amount of objects between the device and the router.
    • Usually, the best place for the router is very high above the ground, as there are less things on the ceiling than the floor.
    • This especially applies to any metallic or perfectly-flat objects as they can reflect the signal, causing even more interference.
  • Optimize your router's settings. This can include doing things like enabling Quality of Service (QoS), Smart Queue Management (SQM), etc.
    • Typically only modern high-end routers support these features, as they require a bit more CPU power than just normal networking does. If your router supports installing OpenWRT onto it, it likely also supports this setting.
  • If your device has other wireless interfaces such as Bluetooth or internal Wi-Fi (and you're using a USB dongle), turn them off.
    • This is especially so if you only have 2.4 GHz Wi-Fi, as that operates near the same frequency as Bluetooth.

You can disable the Raspberry Pi 4's onboard Wi-Fi by adding dtoverlay=disable-wifi to /boot/config.txt.

First, check the supported controllers page. If you're using a controller not listed there, it should still work however, but there may be undocumented issues.

Check the following:

  • Make sure that you've put your controller into its “Pairing” mode. This differs between controllers, but usually involves holding down a few buttons as you turn on the controller.
  • If failing to re-pair a controller, that you've cleared the previously remembered controllers from memory.
  • That there is no significant wireless interference, such as USB 3.0 drives, Wi-Fi routers nearby, microwaves turned on, a large sheet of metal, a dog barking really loudly, etc.
  • That you're only using one Bluetooth interface. eg. if you have an on-board BT module and a USB-connected BT dongle, they might disrupt each other.
  • Turn off other wireless interfaces such as Wi-Fi.

You can disable a Raspberry Pi 4's on-board Bluetooth by adding a line containing dtoverlay=disable-bt to the /boot/config.txt file.

You can try manually connecting a Bluetooth device via SSH/xterm instead of using the menu. It could also be that the BT dongle you're using is too new and unsupported by Batocera; here's a list of confirmed working dongles.

You should also try plugging the BT dongle into a USB 2.0 port instead of a USB 3.0 port, as some BT dongles have issues with 3.0 ports (noted in the compatible dongle list).

Some users have reported Bluetooth to stop working indefinitely if the userdata partition ever becomes completely full (such as by scraping), even after freeing up some space afterwards. The only reported solution to this is to reflash Batocera.

If your Bluetooth device complains about requiring certain binary firmware files (check with dmesg), you can put them into /lib/firmware/rtl_bt/ and run batocera-save-overlay after confirming it works.

An example of a BT device complaining about binary firmware files in dmesg:

[    1.797311] Bluetooth: hci0: RTL: firmware file rtl_bt/rtl8761b_fw.bin not found

If you've done this and it worked successfully, let the devs know so they can add it to the next version of Batocera.

First, check the supported controllers page. If you're using a controller not listed there, it should still work however, but there may be undocumented issues.

If you have the option, use a wired connection. Wireless connections have far more things that can “go wrong” to make your controller not work, whereas wired has a much higher chance of working correctly. If you'd still like to use a wireless Bluetooth connection, check the Bluetooth issues section above.

If using a third-party controller, they may have multiple “modes” that they can be put into. Try each of them, replugging the device between switching modes. Typically the X-input mode should work fine, followed by the D-input mode.

If you'd like to get your hands dirty with SSH and evtest, refer to this page for joystick issue diagnosis.

Windows has a tendency to “lock” the hard-drive that it's on when it shuts-down, rendering it inaccessible to any other operating system. Very cool. To test for this, you can perform a proper shutdown by holding down the Shift key while selecting "Shut down" from the Start menu.

To turn off “fast startup (hybrid boot)”:

  1. Open the old Control Panel (icons view), accessible from the Start menu search, and click on the Power Options icon.
  2. Click the Choose what the power buttons do link on the left side.
  3. Click the Change settings that are currently unavailable link at the top (administrator permissions required).
  4. Under Shutdown settings, uncheck the Turn on fast startup box.
  5. Click the Save changes button.

Details for Windows 8 on the eightforums. Details for Windows 10 on the tenforums.

In addition to this, there may be a setting in your BIOS configuration that also needs to be disabled. This can be referred to as “Fast boot”, “Windows 8.1/10/11 boot/feature”, “Hybrid sleep”, etc. Every BIOS is different, refer to your motherboard's manual.

Maybe you have Bitlocker drive encryption enabled? This is a feature of Windows that allows you to encrypt your drive's data such that only Windows can see it. It is not enabled by default, but it could have been unintentionally activated.

First, type “bitlocker drive encryption” into the Start menu and select the identically named option. Make sure your hard-drive says “Off” in its Bitlocker encryption status.

Additionally, individual folders/files may have been encrypted. Locate the “inaccessible” folder/file in question in Windows, right-click → PropertiesAdvanced.. and uncheck “Encrypt contents to secure data”.

This is not actually Batocera, Windows will just overwrite the RTC value with the localized time, whereas Batocera uses the more globally accepted UTC time. If you'd rather not mess with Windows' registry at all, you can just tell Windows not to update the time via the Internet time. Right-click the time on your taskbar to get into its properties to change this. However, this will mean the time displayed on your Windows machine will not be correct. If you'd like correct time on both operating systems, read the following sections:

The fix for this on Windows (summarized from the Arch wiki's page about it):

  1. Hit [Winkey]+[R] and run “regedit”. Confirm administrator privileges
  2. Make a backup by going to FileExport…
  3. Navigate to HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation\
  4. Add a DWORD value with hexadecimal value 1 named RealTimeIsUniversal

    For 64-bit versions of Windows 7 and older builds of Windows 10, there was a bug that made it necessary to have a QWORD value with hexadecimal value of 1.

  5. Yeehaw, you're done. Windows might ask to update the clock, let it do so

You can also just download and install/import this reg file (if you trust strangers on the internet):

UTCtimefix.reg
Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\TimeZoneInformation]
     "RealTimeIsUniversal"=dword:00000001

Just double-click the file, or go to Regedit's FileImport… menu. It is strongly recommended to only use this on the later versions of Windows 10.

You can use a custom script in Batocera v32 and up to tell it to use the local time just like Windows does instead.

Put the following file into /boot/boot-custom.sh:

boot-custom.sh
#!/bin/bash

if test "$1" != "start"
then
  exit 0
fi

TZ=Europe/Paris
hwclock --systz --localtime

with of course your local timezone (TZ=) instead and mark it as executable.

Credit to @NostalgicD for working this out.

If you are a Mac user, you might wonder why you see lots of files starting with ._ and that are duplicates of your actual rom files, or other files, (like you have a 1943.zip file and next to it ._1943.zip. This is because you accessed your Batocera machine from a Mac, and MacOS leaves this files that are hidden by default under Linux, because they start with a dot, but might still appear in EmulationStation.

In order to list them all, you SSH into your Batocera system and enter:

find /userdata/ -name "._*"

And to remove them all:

find /userdata/ -name "._*" -exec rm {} \;

In case you want to share a snapshot of your system log files to help developers diagnose your machine you can use the menu SYSTEM SETTINGSDEVELOPERCREATE A SUPPORT FILE. It will generate a tarball in /userdata/saves/ named batocera-support-YYYYMMDDHHMMSS.tar.gz (with year/date/time of creation in the filename). You could also create this by running batocera-support from SSH. This tarball might contain sensitive data such as your Wi-Fi/RetroAchievements password in plain-text, so be careful of where you share it to. Your:

  • Wi-Fi SSID and password is in system/batocera.conf and system/batocera-boot.conf
  • RetroAcheivements username and password are in system/batocera.conf
  • ScreenScraper username and password are in system/config/emulationstation/es_settings.cfg

You could also just use a freshly installed Batocera that contains no such information instead to create the support file.

Systems will not show up in the EmulationStation system list unless you have a ROM in their respective folder(s). All available cores are always installed by Batocera; you never need to “add” cores. There is a compatibility chart on the main website.

If you're having issues with a particular system, first refer to its respective system page, as it may mention common problems and their solutions there instead. Here are some frequent issues:

Nintendo 3DS (Citra)

  • Does not support encrypted games, they must be decrypted

PlayStation 2 (PCSX2)

  • Bios may be needed if having graphical issues and boot issues
  • Most games let you invert your controls if you feel the left stick is swapped
  • Compatibility between games and PCSX2 emulator can be checked on this webpage
  • To access all configuration options for PCSX2, you need to run its app in APPLICATIONS menu of the File Explorer that you can access by pressing F1 on your PC keyboard, from the systems menu

GameCube and Wii (Dolphin)

Nintendo 64 (Mupen64Plus)

  • The standalone Mupen64Plus emulators cannot read compressed files (.zip, .7z, etc.); this is not an issue on the Libretro cores

When things go really wrong, and you want to “factory reset” your Batocera, i.e. putting all the settings to their default values without losing your ROMs, saves and scraped metadata, there is a method to do it:

  • If accessing the userdata partition from the network, simply rename the directory system/ to system.old and reboot.
  • If you are connected through SSH, just enter mv /userdata/system /userdata/system.old and then reboot.

Those two commands are the same, and upon reboot, all your settings will be cleared out to their default values. You'll have to re-enter some parameters like your Wi-Fi credentials and so on… or, you can look at what you have in the previous configuration files in the /userdata/system.old/batocera.conf file and all the files in the /userdata/system.old/configs/ folder. Reinsert your settings one by one until you come across the one that causes the issue. This way you can set up your previous configuration without re-entering everything (in particular for batocera.conf, you might have many options set in there), excluding the setting that causes the issue of course.

If not even this resolves your issue, as a last resort you can try re-flashing Batocera. This will obviously wipe all of your userdata (ROMs, saves, etc.) in the process (if stored on the same drive).

  • troubleshooting.1634258173.txt.gz
  • Last modified: 2 years ago
  • by atari