Repository navigation
Troubleshooting
BlizzHacker edited this page Nov 17, 2026
·
1 revision
Start by checking the version under System → Status. Many "bugs" are an older build.
| Symptom | Likely cause and fix |
|---|---|
| Download finished but never imports | The client and ROMarr see the download at different paths. Mount it at the same path, or add a remote path mapping under Settings → Media Management. |
| Import fails with a permission error |
PUID/PGID don't match the owner of your ROM or download folders. |
| No search results | Test the indexer; check Prowlarr's indexers and game categories; try the same search on the indexer's site. |
| A grab fails straight away | No client is configured for that release's protocol (torrent vs Usenet). |
| RomM doesn't show an imported game | RomM must scan the same folder ROMarr wrote to, and its rescan must finish. |
| Changing an environment variable did nothing | After first run, connection settings live in the web UI. Edit them there. |
localhost client can't be reached from Docker |
Inside a container, localhost is ROMarr itself. Use the client's service name or host IP. |
| Plugins refuse to run | Plugin confinement isn't available on this host. See ROM Hub Plugins. |
| Switch report says "incomplete" | A scan limit was hit or a folder changed. Use Refresh; very large shelves may stay partial. |
| Soundtracks page is missing | Add a RomM library first. |
Slow scans or temporary storage errors on a NAS? See NAS-LIBRARIES.md.
Activity → Reports & Help lets you record a local file report, run a scanner on a snapshot, and quarantine or restore files. Nothing is deleted. See REPORTING.md.
Open an issue with:
- your ROMarr version and install method;
- what you did, what you expected, and what happened;
- the relevant log lines.
Remove passwords, API keys and webhook URLs first.
ROMarr is MIT licensed · Report a problem · Detailed, release-tracked docs live in the repository's docs folder.