Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
troubleshooting [2023/03/03 09:30] – Add: BT troubleshooting mutliple BT controller issues grandmabettytroubleshooting [2026/03/28 18:41] (current) – ↷ Links adapted because of a move operation 92.184.108.195
Line 1: Line 1:
 ====== System Troubleshooting ====== ====== System Troubleshooting ======
 +
 +If going to our [[https://discord.gg/ndyUKA5|Discord]] for help, gather the relevant logs (as described below) and upload them along with your message. This will help us help you better.
  
 ===== Emulators not launching/EmulationStation logs ===== ===== Emulators not launching/EmulationStation logs =====
Line 45: Line 47:
   * [[systems:steam|Steam]]   * [[systems:steam|Steam]]
   * [[systems:windows|Windows]]   * [[systems:windows|Windows]]
-  * [[systems:wiiu|Wii U]]+  * [[systems:wiiu|Wii U]] (for Batocera **v36** and below)
   * [[systems:model2|Model 2]]   * [[systems:model2|Model 2]]
-  * FIXME possibly more...+  * [[systems:fpinball|Future Pinball]] 
 +  * [[systems:jaguar|Jaguar]] (BigPEmu) 
 +  * [[systems:halflife|xash3d_fwgs]]
  
-If you want to continue using your NAS for the majority of your games, but to use your internal storage for these affected systems so they can continue to work (not being on your NAS, obviously), save the following script as ''/userdata/system/custom.sh'': 
  
-<file bash custom.sh>+If you want to continue using your NAS for the majority of your games, but to use your internal storage for these affected systems so they can continue to work (not being on your NAS, obviously), save the following file as a [[scripting_services_rules_examples#batocera_services|service]] in ''/userdata/system/services/nas_workaround'' (no extension): 
 + 
 +<file bash nas_workaround>
 #!/bin/bash #!/bin/bash
 # This allows you to still use Windows/Flatpaks even while using a NAS. # This allows you to still use Windows/Flatpaks even while using a NAS.
Line 58: Line 63:
     start)     start)
         mkdir -p /media/SHARE/saves/flatpak         mkdir -p /media/SHARE/saves/flatpak
-        mount /media/SHARE/saves/flatpak /userdata/saves/flatpak+        mount --bind /media/SHARE/saves/flatpak /userdata/saves/flatpak
         mkdir -p /media/SHARE/saves/windows         mkdir -p /media/SHARE/saves/windows
-        mount /media/SHARE/saves/windows /userdata/saves/windows+        mount --bind /media/SHARE/saves/windows /userdata/saves/windows
         mkdir -p /media/SHARE/roms/windows         mkdir -p /media/SHARE/roms/windows
-        mount /media/SHARE/roms/windows /userdata/roms/windows+        mount --bind /media/SHARE/roms/windows /userdata/roms/windows
         ;;         ;;
 esac esac
Line 69: Line 74:
  
 </file> </file>
 +
 +After uploading or creating the file, run ''batocera-services enable nas_workaround'' to activate the service at boot. Rebooting or running ''batocera-services start nas_workaround'' should create all the nescessary mountpoints in /media/.
 +
 +<WRAP center round info>
 +Batocera **v36** and below do not require the ''%%--bind%%'' option for the mount commands.
 +</WRAP>
  
 ===== Poor game performance ===== ===== Poor game performance =====
Line 75: Line 86:
  
 Once you're sure that your game's poor performance is abnormal, and your system is ordinarily capable of much better, here are a few things you can try: Once you're sure that your game's poor performance is abnormal, and your system is ordinarily capable of much better, here are a few things you can try:
-  * If you haven't already, [[:supported_pc_hardware|activate the drivers]] as appropriate for your hardware. Typically, only Nvidia GPUs need this to be done. Radeon/AMD GPUs are already "activated" and require no action. 
   * Reset all your settings back to "AUTO", these use sane defaults which should perform well in most circumstances.   * Reset all your settings back to "AUTO", these use sane defaults which should perform well in most circumstances.
-  * Change the graphics API being used by your emulator. This can typically be found in the system's advanced settings. Not all emulators have access to all APIs. From best to worst: Vulkan, GLCore, OpenGL.+  * Change the graphics API being used by your emulator; each piece of hardware may prefer or run slower with any given API. This can typically be found in the system's advanced settings. Not all emulators have access to all APIs. From newest to oldest: Vulkan, GLCore, OpenGL.
   * Ensure that your audio buffer isn't being choked; if your system is unable to process audio frames as quickly as they are being produced, this could put a throttle on the device's performance. [[:audio_issues#my_audio_is_randomly_cutting_out_depending_on_what_s_happening_on_screen|Try increasing the audio latency setting in the advanced system options.]]   * Ensure that your audio buffer isn't being choked; if your system is unable to process audio frames as quickly as they are being produced, this could put a throttle on the device's performance. [[:audio_issues#my_audio_is_randomly_cutting_out_depending_on_what_s_happening_on_screen|Try increasing the audio latency setting in the advanced system options.]]
   * Remove any [[:launch_a_script|custom scripts]] in ''/userdata/system/scripts/'' (or rename the ''scripts/'' folder to ''backupscripts/'' to temporarily disable them), ''/boot/boot-custom.sh'' and/or ''/userdata/system/custom.sh''.   * Remove any [[:launch_a_script|custom scripts]] in ''/userdata/system/scripts/'' (or rename the ''scripts/'' folder to ''backupscripts/'' to temporarily disable them), ''/boot/boot-custom.sh'' and/or ''/userdata/system/custom.sh''.
   * Lower the resolution of your game. This is especially so if the system isn't normally meant to be upscaled, like fifth generation and below consoles.   * Lower the resolution of your game. This is especially so if the system isn't normally meant to be upscaled, like fifth generation and below consoles.
 +  * If using Nvidia hardware and on Batocera **v33** or lower, [[:supported_pc_hardware|activate the official Nvidia drivers]]. If on Batocera **v34** or higher, or using hardware other than Nvidia (such as AMD), this is all automatically handled and no action is required.
  
 If you're still having poor performance after checking all of the above, come to the [[https://discord.com/invite/JXhfRTr|Discord server]] along with your logs (preferably, with a video of the low performance in action) and you should get some pointers. If you're still having poor performance after checking all of the above, come to the [[https://discord.com/invite/JXhfRTr|Discord server]] along with your logs (preferably, with a video of the low performance in action) and you should get some pointers.
Line 168: Line 179:
 You can first check for the BIOS settings on [[install_batocera#bios_settings_if_batocera_fails_to_boot|the install Batocera page.]] Then, check for the following: You can first check for the BIOS settings on [[install_batocera#bios_settings_if_batocera_fails_to_boot|the install Batocera page.]] Then, check for the following:
   * You may need to change your BIOS to allow legacy/unsecured boot, as some motherboards may only allow Windows to boot on UEFI.   * You may need to change your BIOS to allow legacy/unsecured boot, as some motherboards may only allow Windows to boot on UEFI.
-  * If your BIOS is UEFI only and you can't use legacy boot, make sure that it can load ''EFI/boot/bootx64.efi'' from Batocera's boot partition. Some motherboards require the keys to be added manually, this usually can be done from the security options of the BIOS. Search for an option which allows you to "Add keys", "Generate keys from EFI file" or "Enroll Efi image":\\ {{:bios_security_efi_keys_options.jpeg?400|Photo of a motherboard BIOS showing security options, "Enroll Efi Image" is visible.}}+  * If the system has a UEFI BIOS, and Secure Boot can't be disabled, and legacy boot is not available, see the [[secureboot|Secure Boot]] page for setup instructions. 
 +  * If the system has a Trusted Platform Module (TPM) that is enabled, Batocera **v39** and higher will display ''Boot Option Restoration'' and reboot after five seconds, repeating until the required  [[secureboot#TPM|TPM Configuration]] is performed. 
 +  * If using Grub bootloader on UEFI to chainload the Batocera bootloader, ensure that the correct path is being chainloaded: 
 +    * For Batocera **v39** and higher: ''/EFI/batocera/bootx86.efi'' 
 +    * For Batocera **v38** and lower: ''/EFI/BOOT/bootx86.efi''
   * 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.)   * 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.)
     * Windows 8 and above have renamed the "Hibernate" function to "Shut down" (technical term is "fast startup (hybrid shutdown)"). To properly shutdown, [[https://www.top-password.com/blog/fully-shutdown-windows-10-instead-of-hibernating-it/|hold down the SHIFT key while selecting "Shut down" from the Start menu]]. [[#batocera_can_t_read_my_hard-drive_using_its_file_manager_i_know_it_s_fine_because_i_boot_windows_off_of_it|You can also permanently turn this "feature" off.]]     * Windows 8 and above have renamed the "Hibernate" function to "Shut down" (technical term is "fast startup (hybrid shutdown)"). To properly shutdown, [[https://www.top-password.com/blog/fully-shutdown-windows-10-instead-of-hibernating-it/|hold down the SHIFT key while selecting "Shut down" from the Start menu]]. [[#batocera_can_t_read_my_hard-drive_using_its_file_manager_i_know_it_s_fine_because_i_boot_windows_off_of_it|You can also permanently turn this "feature" off.]]
Line 178: Line 193:
   * Try disabling/enabling the IOMMU setting in your BIOS.   * Try disabling/enabling the IOMMU setting in your BIOS.
   * Try switching AHCI/SATA/NVMe settings in your BIOS for the drives in question (some BIOS only have this as a global setting).   * Try switching AHCI/SATA/NVMe settings in your BIOS for the drives in question (some BIOS only have this as a global setting).
-  * Ensure that ''nvidia-driver'' and ''nvidia-prime'' are set to ''false'' in ''batocera-boot.conf''. [[:edit_boot_partition|How to edit the boot partition.]] +  * If your motherboard's EFI shell is unable to load or select Batocera's EFI partition (common on Mac hardware), consider replacing it with the more universal [[https://www.rodsbooks.com/refind/|rEFInd Boot Manager]]. It's recommended to read through the entire page and understand it first before going through with the process.
-  * If your motherboard's EFI shell is unable to load or select Batocera's EFI partition (common on Mac hardware), consider replacing it with the more universal [[https://www.rodsbooks.com/refind/|rEFI Boot Manager]]. It's recommended to read through the entire page and understand it first before going through with the process.+
  
 === Verbose boot === === Verbose boot ===
Line 210: Line 224:
  
 <-- <--
 +
 +=== Legacy boot ===
 +
 +On x86_64 legacy boot systems, if the file ''/boot/boot/syslinux/ldlinux.sys'' is modified in **any** way, a situation may be created where future modifications of any kind to the ''BATOCERA'' /boot partition (including Batocera version upgrades/downgrades) may trigger a black screen at boot with the message "Boot error".
 +
 +To recover from this:
 +  - Boot from a Linux distribution on another drive (procedure was tested with the live installer''ubuntu-23.10.1-desktop-amd64.iso'')
 +  - Get to a root shell ("Try Ubuntu", start a terminal, ''sudo -i'')
 +  - Attach the Batocera drive, if not already attached
 +  - Ensure that the Batocera boot partition is **not** mounted: ''umount $(blkid -L BATOCERA)''
 +  - Ensure that the "syslinux" package is installed.  For a Debian or Ubuntu system: ''apt install syslinux''
 +  - Reinstall the bootloader (Note: It's OK if this produces warnings like "Hidden (2048) does not match sectors (63)"): ''syslinux -i $(blkid -L BATOCERA) -d /boot/syslinux''
 +
  
 ==== Single board computer (RPi, Odroid, etc.) ==== ==== Single board computer (RPi, Odroid, etc.) ====
Line 232: Line 259:
 ===== Video/display issues ===== ===== Video/display issues =====
  
-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). +<WRAP center round tip> 
- +[[:display_issues|Has been moved to its own page.]] 
-Next, check that the settings on your TV are correct. Most modern displays offer a "Overscan" setting or something similar that zooms in the image slightly, cutting off the edges of the screen. Turn settings like these off. +</WRAP>
- +
-It may also help to [[:supported_pc_hardware|activate your Nvidia drivers/Intel drivers]] if using those applicable devices. +
- +
-Several video issues on PC x86 and x86_64 can be investigated [[display_issues|with xrandr as described on this page]].+
  
 ==== Incorrect radeon/amdgpu driver selected ==== ==== Incorrect radeon/amdgpu driver selected ====
Line 265: Line 288:
 amdgpu.dc=1 amdgpu.dc=1
 </code> </code>
- 
-==== Everything is appearing too small in the file manager! ==== 
- 
-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 
  
 ===== Network issues ===== ===== Network issues =====
- 
-==== Console access ==== 
  
 <WRAP center round tip> <WRAP center round tip>
-Has been moved to its [[:network_issues|own page]].+[[:network_issues|Has been moved to its own page]].
 </WRAP> </WRAP>
- 
  
 ===== Bluetooth issues (not connecting, no devices detected, etc.) ===== ===== Bluetooth issues (not connecting, no devices detected, etc.) =====
Line 295: Line 306:
   * 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.   * 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.   * Turn off other wireless interfaces such as Wi-Fi.
-  * Make sure your computer does only have a //single// Bluetooth controller installed! Many mainboards have a dedicated on-board Bluetooth controller installed which would cause different problems when an additional Bluetooth controller (e.g. Bluetooth USB dongle) is installed. 
  
 <WRAP center round tip> <WRAP center round tip>
Line 354: Line 364:
 ==== I can see the drive but still can't access it! ==== ==== I can see the drive but still can't access it! ====
  
-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.+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 enabled by default since around 2024.
  
 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. 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.
Line 374: Line 384:
 ===== Create a Batocera support file ===== ===== Create a Batocera support file =====
  
-In case you want to share a snapshot of your system log files to [[:report_issue|help developers diagnose your machine]] you can use the menu **SYSTEM SETTINGS** -> **DEVELOPER** -> **CREATE 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 [[:access_the_batocera_via_ssh|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:+In case you want to share a snapshot of your system log files to [[:report_issue|help developers diagnose your machine]] you can use the menu **SYSTEM SETTINGS** -> **FRONTEND DEVELOPER OPTIONS** -> **CREATE 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 [[:access_the_batocera_via_ssh|SSH]].  
 +<WRAP center round important> 
 +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''   * Wi-Fi SSID and password is in ''system/batocera.conf'' and ''system/batocera-boot.conf''
   * RetroAcheivements username and password are in ''system/batocera.conf''   * RetroAcheivements username and password are in ''system/batocera.conf''
Line 381: Line 393:
 You could also just use a freshly installed Batocera that contains no such information instead to create the support file. You could also just use a freshly installed Batocera that contains no such information instead to create the support file.
  
 +In Batocera **39** or later, most sensitive data will be scrubbed from the support file automatically.  Please file a Github issue report if any sensitive data is found in support files from recent versions.
 +</WRAP>
 ===== Factory reset ===== ===== Factory reset =====
  
  • troubleshooting.1677835802.txt.gz
  • Last modified: 3 years ago
  • by grandmabetty