Troubleshooting¶

Start with Settings → Connection test: it checks the connection step by step and says what to do when a step fails. The most common problems are below, with the message shown by the app.

Installation and server¶

"Cannot connect to the Docker daemon" or "docker: command not found"¶

Docker Desktop is not running (macOS, Windows) or the Docker service is stopped (Linux). Start it, wait until the engine is running, then run the command again.

Windows: "WSL 2 installation is incomplete"¶

WSL 2 or virtualization is not turned on. Follow Microsoft's WSL guide, restart, then start Docker Desktop again.

Linux: "permission denied" on the Docker socket¶

Your user has no rights on Docker. Use sudo, or follow the post-installation steps.

The page does not open, or "The local server is not responding"¶

ROMKADE Manager is not running. In the romkade folder:

docker compose ps
docker compose up -d

If the service keeps restarting, docker compose logs romkade shows why. From the source code: start ./run.sh again.

Port 8765 is already in use¶

docker compose up fails with "port is already allocated": another program uses the port. Start ROMKADE Manager on another one, for example ROMKADE_PORT=8780 docker compose up -d (PowerShell: $env:ROMKADE_PORT=8780; docker compose up -d), then open http://localhost:8780.

From the source code, run.sh stops and shows which program holds the port, usually a previous instance: kill $(lsof -t -iTCP:8765 -sTCP:LISTEN), then ./run.sh.

"manifest unknown" or "denied" when downloading the image¶

The image name or version in compose.yaml is wrong, or the file was not downloaded from the official release. Download it again with the command of the Installation page.

Connection¶

The console is unreachable¶

"Console unreachable". Check that:

the console is on, Wi-Fi turned on, not in sleep mode;
the computer and the console are on the same network (not a guest network);
the address in Settings → Connection is still the console's: it can change after the router restarts.

macOS blocks local network access¶

"macOS blocks local network access for the Game Manager server", or "No route to host" while the console answers. macOS forbids the app that runs ROMKADE Manager to reach the local network.

Open System Settings → Privacy & Security → Local Network.
Turn on Docker (Docker installation), or the app that started ./run.sh (Terminal, iTerm, VS Code…).
Restart: quit and reopen Docker Desktop, or Ctrl+C then ./run.sh.

From the source code, the same symptom appears with Homebrew's Python: use Python from python.org.

Windows: the console is unreachable with Docker¶

Windows Firewall may block Docker on the network type in use. Check that your Wi-Fi network is set as Private, and that Docker Desktop is allowed for private networks in the firewall settings.

The console refuses SSH connections¶

"The console refuses SSH connections". The console answers but SSH is off: turn SSH on in the console's settings, or check the port in Settings → Connection.

The password is rejected¶

"The console refused SSH authentication". Update the password in Settings → Connection (Replace the password). With an SSH key, check that its public key is in ~/.ssh/authorized_keys on the console.

The console's key has changed¶

"The console's key has changed". The device at this address presents a different key from the one you approved. It is expected after reinstalling the firmware or changing the card; otherwise it may be another device. Check the fingerprint again with ssh-keyscan (see Connection) before approving the new key.

"The ROMs folder cannot be found" or "The ROMs folder is empty"¶

Check that the card is in place, then the path in Settings → Connection. Settings → System offers the folder found on the console. When the folder is empty while the catalog has games, the sync is refused and nothing changes.

Games¶

"Remote launch is not possible"¶

On Anbernic, launching remotely needs the Stock OS Mod. On other firmwares, check what the profile allows in Settings → System and on Supported consoles.

The console's buttons no longer control the game¶

Player 1 is still assigned to a controller that is not plugged in. Open Controllers and click Use the console buttons.

No box art¶

"Box art library unreachable": the computer has no Internet access. Box art already downloaded stays available. Some games have no box art in the libretro collection: switch Images to Card images in the library.

"Not enough space on the card"¶

The copy needs the size of the files plus a 256 MB margin. Remove files from the list or free space on the card.

Saves¶

"A game is running on the console"¶

Restoring or deleting a save is refused during a game, because the game would rewrite the file when quitting. Quit the game first.

Bluetooth¶

A controller does not pair¶

Recent controllers (Xbox, 8BitDo…) only pair during an active search. Put the controller in pairing mode, click Search for devices, then Pair and connect. If it is paired but does not respond, wake it up (Xbox or Home button) and click Connect.

Devices are gone after a restart¶

The Anbernic firmware erases Bluetooth pairings at every start. Pair them again from the Bluetooth page.

No sound on the Bluetooth speaker¶

Click Send game sound here next to the speaker, then launch the game from ROMKADE Manager: games launched from the console's own menu keep using its speakers.

Search¶

Search does not tolerate typos¶

Typesense is not running, so the built-in search is used. Start Docker Desktop, then restart ROMKADE Manager.

Still stuck?¶

See About to report the problem. Include the message shown, the console model and its firmware.