Troubleshooting

"I don't know how to SSH into my console"

SSH is how you run commands on your Batocera machine from another computer. You only need to do this once.

First, find your console's IP address: On your Batocera, go to the main menu (Start button) → Network Settings. Your IP will look like 192.168.x.x.

Then, on your computer:

• Windows 10/11: Open PowerShell or Command Prompt and type: ssh root@192.168.x.x (replace with your IP)
• Mac: Open Terminal and type the same command
• When asked for a password, type: linux (you won't see it as you type — that's normal)

Once connected, paste the install command and press Enter.

"Batocera version 41 or newer is required"

Outbreak requires Batocera v41+. If you're on an older version, you'll need to update Batocera first.

Go to the Batocera main menu (Start button) → System Settings → Updates & Downloads → Start Update. Your console will download and install the latest version automatically. This preserves your games and saves.

"Download failed" or "No internet connection"

The installer needs internet access to download Outbreak.

• Wired: Make sure the Ethernet cable is plugged in before running the installer
• WiFi: Connect to WiFi first via Batocera → Network Settings. Then re-run the installer
• Test your connection: ping -c 3 github.com

The installer finished but nothing seems different

Outbreak runs in the background. You won't see changes on your TV until you scroll through the carousel.

• Look for Outbreak Host and Outbreak Lobby in your EmulationStation carousel (scroll left/right past your game systems)
• Open the web panel: http://YOUR_IP:8765/ui in any browser on the same network
• If neither appears, reboot your console and wait 60 seconds for Outbreak to start

My game list is empty or shows very few games

After installation, Outbreak scans your library and begins downloading missing games automatically. This runs in the background and can take 20-60 minutes depending on your internet speed.

• Open the web panel (http://YOUR_IP:8765/ui) and look for download progress indicators
• The Outbreak Host carousel will populate as games finish downloading
• Arcade games (FBNeo) download as a single large pack — they'll all appear at once when the pack finishes extracting

Learn more about how auto-download works: Auto-Download Guide

A specific game won't launch or I see a black screen

This usually means the ROM file is missing or doesn't match the expected version.

• Use the ROM Checker in the web panel (gear icon) to verify your ROMs
• Check the ROM Guide for the exact filename required
• Both players must have the exact same ROM file for netplay — even small differences will cause failures

I hosted a game but no one can see it

Sessions take 15-30 seconds to appear on other consoles.

• Make sure both consoles are on the same network (for LAN play), or both have internet (for WAN play)
• Open the web panel on the joining console — the session should appear there
• If playing over the internet (WAN), sessions appear in the Live Lobby once they're announced

Join fails or the game doesn't start on the second console

The most common cause is a ROM mismatch — both players need byte-identical ROM files.

• Make sure both consoles have completed the auto-download process
• If you added ROMs manually, use the same source for both consoles
• Try hosting a different game to confirm the connection works

"Connection too slow" or high latency

Netplay is sensitive to network latency. A wired Ethernet connection makes a big difference.

• Best: Both consoles on wired Ethernet, same local network (LAN) — under 5ms
• Good: Both consoles on wired Ethernet, different locations (WAN) — 20-80ms
• Playable: One console on WiFi — 40-120ms
• Not recommended: Both consoles on WiFi — inconsistent, frequent stuttering

Arcade games (FBNeo) use rollback netcode, which handles latency much better than other systems. If you're on a slower connection, stick to arcade games for the smoothest experience.

The game desyncs or behaves strangely during play

• Make sure both consoles are running the latest version of Outbreak (it auto-updates, but you can force it by re-running the install command)
• Exit the current session and re-host — most desyncs are one-time glitches
• Avoid using save states during netplay

Can't reach the web panel at http://IP:8765/ui

• Same network? Your phone/PC must be on the same WiFi or wired network as the console
• Correct IP? Check your console's IP in Batocera main menu → Network Settings
• Console on? The console must be fully booted (past the Batocera splash screen)
• Wait 60 seconds after boot — Outbreak needs a moment to start
• Try from a different browser or device to rule out local issues

Black screen after exiting a game

Sometimes RetroArch doesn't exit cleanly. This is usually a one-time issue.

• Press Select + Start together on your controller (this is the default exit hotkey for RetroArch)
• If that doesn't work, wait 10 seconds and try again
• As a last resort, hold the power button on your console to reboot. Outbreak will restart automatically

Console seems frozen or unresponsive

• Try pressing Select + Start to exit any running game
• If the web panel still loads (http://YOUR_IP:8765/ui), the console is running — just the display may be stuck. Reboot via the web panel or hold the power button
• A reboot will always bring everything back to a clean state