Troubleshooting

This page covers what's been run into and reported so far, organized by symptom so it's a self-service first stop during setup and afterward. It's expected to grow. If you hit something not listed here, that's worth reporting rather than assuming it isn't a known issue.

The container won't start, or keeps restarting

Check the container logs first. A critical log line reading BROKER_SECRET IS NOT SET - REFUSING TO START means the broker refused to boot on purpose: BROKER_SECRET isn't set and BROKER_DEV_MODE isn't either. Fix: set BROKER_SECRET to a real value (see Broker settings), or set BROKER_DEV_MODE=true for local development only, which starts the broker anyway but leaves every session-lifecycle endpoint unauthenticated. It must never be reachable outside your own machine in that mode.

The stream loads, but the screen stays black (or emulators won't draw)

No GPU passed through: the image falls back to software rendering, and most emulators will not run under it. Pass through /dev/dri (Intel/AMD) or the NVIDIA runtime with driver 580 or newer (595.80+ preferred). See Running the container.

NVIDIA specifically: if the GPU is detected and encoding/compute work but nothing ever reaches the screen, the missing piece is almost always the /dev/nvidia-modeset device. The NVIDIA container toolkit adds nvidia0/nvidiactl/uvm automatically, but not this one. nvidia-modprobe --modeset creates it if it doesn't already exist on the host. On Unraid with an older (pre-595) driver, the module can be loaded while the device file is still missing; see Unraid with an older NVIDIA GPU.

PCSX2 on AMD integrated graphics specifically: a "Failed to initialize GS" error at startup means RADV (AMD's Vulkan driver) failed on that hardware. Switch PCSX2's renderer to OpenGL in Settings > Graphics, which uses radeonsi instead and is confirmed to work.

Proxmox LXC: not an officially supported way to run this image (a Docker VM is). Device permissions reset on every host reboot, and rendering falls back to software without extra bind-mounts. See the Proxmox callout on Running the container and Issue #32 for a setup confirmed to work anyway.

Activate fails, or a specific game won't launch

A 404 response with detail rom not found at <path> means this container doesn't have the library at the path RomM uses. Mount the same host folder at the same path as on the RomM container (normally /romm/library). Check with docker exec webstation ls <path> using the path from the error.

A 400 response with detail rom path must live under <root> means the path RomM sent is outside the broker's ROM_ROOT (default /romm). This only comes up when the library is mounted somewhere other than under /romm and RomM's library_path points there: set ROM_ROOT to match. See Mounting the library somewhere else and Broker settings.

The emulator may just need its one-time setup first. Run it through Emulator setup from a desktop session before the first real launch. Eden needs prod keys and firmware installed by hand from its Tools menu. Cemu needs a keys.txt uploaded. Xemu needs three specific files uploaded and a relaunch before it boots anything. shadPS4 needs a version downloaded through its own version manager before it runs at all.

shadPS4 refuses a .pkg file or an archived (.7z/.zip/.rar) ROM outright by default, and RPCS3 refuses an archived ROM the same way (.pkg is unaffected on RPCS3 - it always installs through its own installer regardless). That's SHADPS4_CACHE_ENABLED or RPCS3_CACHE_ENABLED left off, which is the default. Turn the relevant one on to allow those formats. See Configuration and Configuration.

ScummVM extracts archived games by default; PPSSPP only does once PPSSPP_CACHE_ENABLED=true is set. If one refuses an archive, check that its cache is on, and that the archive actually holds the game: ScummVM refuses one with no game files in it, and PPSSPP refuses one with no .iso, .cso, or other PSP image inside.

Xenia never reaches the game, or seems to hang on launch: no Xbox Live profile exists yet. Launch Xenia once from the desktop and create one through its "No Profiles Found" prompt before launching anything through RomM.

The game froze mid-session and the emulator is gone

When an emulator crashes or is quit while a session is open, the stream freezes and the broker logs one line for that session:

emulator watch: session 3f2a...: pcsx2 exited while the session was open (exit code -11, rom Game); exit the session from RomM to save and upload what it wrote

The session stays open on purpose. The saves the emulator wrote before it went are still on disk, and exiting the session from RomM is what dumps them and uploads them. Exit it as soon as you see this.

The exit code says how the emulator ended, and sets the line's level:

The check runs every 15 seconds by default (BROKER_EMULATOR_WATCH_INTERVAL). It skips a check while an exit, launch or state operation is running, since those stop or restart the emulator on purpose.

A controller isn't working

Desktop sessions and single-game launches share the exact same controller configuration, so test with a real controller and a real game from the desktop first, from Emulator setup. For PCSX2 and DuckStation specifically, double check the setup wizard's SDL device order: SDL 0 should be player 1, SDL 1 should be player 2.

Camera, microphone, invite links, or a room that loads and then does nothing

These are reverse-proxy and cross-origin symptoms, not broker ones: a room that loads then sits dead, assets 404ing, camera/mic being refused instantly, invite links falling back to a manual copy box, or a broker-secret 403. All of these already have a full writeup. See Reverse proxy troubleshooting.

Save uploads failing without anyone noticing

The broker keeps a save archive RomM did not take, so nothing is lost, but it tells nobody. Monitoring sets up a check that does, and explains every alert it raises.

Where to look next

The broker's own container logs are the best source of truth for anything happening server-to-server; your browser's console only shows what actually reaches the browser. If nothing here matches what you're seeing, check existing issues or open a new one. That's also how something new ends up added to this page.