Troubleshooting Common RomM Problems and Solutions

ROMs not appearing after scan

If a scan completes but your games don’t show up in the library, work through these checks:1. Verify your folder structureRomM expects ROMs to be inside a library/roms/ directory, organised into sub-folders named by platform slug:

library/
└── roms/
    ├── nes/
    │   └── Super Mario Bros. (USA).nes
    ├── snes/
    │   └── The Legend of Zelda - A Link to the Past (USA).sfc
    └── switch/
        └── The Legend of Zelda - Tears of the Kingdom [01002DA013484000].nsp

2. Check the platform folder nameThe sub-folder name must match a known platform slug (e.g. nes, snes, gb, gba, psx). If you use a different name, you need to add a mapping in config.yml:

filesystem:
  platforms_binding:
    "NES Games": nes    # maps custom folder name → platform slug

3. Check the logs for scan errors

docker logs romm -f | grep -i "error\|warning\|skip"

4. Enable verbose loggingSet LOGLEVEL=DEBUG in your environment and re-run the scan for detailed output on every file processed.

Metadata not loading / artwork missing

1. Verify API keysCheck that the relevant provider API keys are set correctly in your environment:

IGDB_CLIENT_ID and IGDB_CLIENT_SECRET for IGDB
SCREENSCRAPER_USER and SCREENSCRAPER_PASSWORD for Screenscraper
MOBYGAMES_API_KEY for MobyGames
STEAMGRIDDB_API_KEY for SteamGridDB

Missing or incorrect credentials cause metadata fetches to fail silently for that provider.2. Check network connectivityMake sure your RomM container can reach the metadata provider APIs:

docker exec romm curl -s https://api.igdb.com -o /dev/null -w "%{http_code}"

If you are behind a corporate proxy, set HTTP_PROXY and HTTPS_PROXY in your environment.3. Watch for rate limitsScreenscraper enforces strict per-day and per-minute request limits on free accounts. If you see 429 responses in the logs, reduce SCAN_WORKERS to 1 and space out your scans. Screenscraper also blocks requests made without a registered username/password.4. Re-scan with metadata enabledAfter fixing credentials, trigger a new scan from Administration → Scan Library or via the API. Use Full Scan rather than Quick Scan to re-fetch metadata for all games.

Database connection error on startup

RomM logs a database connection error and refuses to start if it cannot reach MariaDB. Common causes:1. Incorrect environment variablesEnsure these four variables match the MariaDB container configuration exactly:

# RomM service
environment:
  - DB_HOST=romm-db        # must match the MariaDB service name
  - DB_NAME=romm           # must match MARIADB_DATABASE
  - DB_USER=romm-user      # must match MARIADB_USER
  - DB_PASSWD=secret       # must match MARIADB_PASSWORD

2. DB_HOST must be the Docker service name, not localhostInside Docker Compose, containers talk to each other by service name. Using localhost or 127.0.0.1 will fail because those point to the RomM container itself, not the database container.3. Database container is not healthy yetIf RomM starts before MariaDB finishes initialising, the connection will fail. The example docker-compose.yml includes a health check and depends_on condition to handle this:

depends_on:
  romm-db:
    condition: service_healthy
    restart: true

Run docker ps and check that the romm-db container shows (healthy) in its status column. If it shows (starting), wait a minute and restart RomM.4. Wrong database driverThe default driver is mariadb. If you are using MySQL or PostgreSQL, set ROMM_DB_DRIVER=mysql or ROMM_DB_DRIVER=postgresql accordingly.

Cannot log in / setup wizard not appearing

ROMM_AUTH_SECRET_KEY is not setThis variable is required. Without it, RomM cannot sign or verify tokens and will reject all logins. Generate one with:

openssl rand -hex 32

Then add it to your environment:

environment:
  - ROMM_AUTH_SECRET_KEY=<your_generated_key>

Setup wizard not showing on first bootIf the setup wizard does not appear after a fresh install, check that DISABLE_SETUP_WIZARD is not set to true. The wizard only shows when no admin user exists in the database.OIDC login not working

Verify OIDC_REDIRECT_URI matches the redirect URI registered with your OIDC provider exactly (including trailing slashes).
Check OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, and OIDC_SERVER_METADATA_URL are correct.
Set LOGLEVEL=DEBUG to see detailed OIDC request and response logging.
If using a self-signed certificate, point OIDC_TLS_CACERTFILE to your CA bundle.

EmulatorJS not loading games in the browser

1. Check that EmulatorJS is enabledMake sure DISABLE_EMULATOR_JS is not set to true in your environment.2. Verify the ROM format is supportedEmulatorJS does not support every ROM format for every core. For example, encrypted Switch NSP files cannot be played in-browser. Check the EmulatorJS documentation for supported formats per platform.3. Check the browser consoleOpen your browser’s developer tools (F12) and check the Console and Network tabs for errors. Common issues include:

CORS errors if RomM is accessed via an unusual hostname
WebAssembly blocked by a Content Security Policy on a reverse proxy
Core files failing to load due to a 404

4. Content Security Policy on reverse proxiesIf you use nginx, Caddy, or another reverse proxy, ensure it does not set a Content-Security-Policy header that blocks wasm-eval or cross-origin resource loading required by EmulatorJS.

Permission denied errors on files or volumes

RomM needs read/write access to the volumes mounted at /romm/library, /romm/resources, and /romm/assets.1. Check host directory permissionsThe RomM container runs as a non-root user. The host directories must be readable and writable by the UID the container uses. Check the image documentation for the default UID, or run:

docker exec romm id

Then adjust host permissions:

sudo chown -R <uid>:<gid> /path/to/library /path/to/resources /path/to/assets

2. Verify volume mounts in docker-compose.yml

volumes:
  - /path/to/library:/romm/library
  - /path/to/assets:/romm/assets
  - romm_resources:/romm/resources

Make sure the host paths exist and are not typos.3. SELinux / AppArmorOn systems with SELinux enabled (e.g. Fedora, RHEL), volume mounts may need a :z suffix to relabel the directory:

volumes:
  - /path/to/library:/romm/library:z

High CPU usage during scan

Library scans are CPU and I/O intensive, especially on large collections. Several settings can reduce the impact:1. Reduce scan workersOn low-power hardware (e.g. a Raspberry Pi or older NAS), reduce the number of parallel scan workers:

environment:
  - SCAN_WORKERS=1

2. Skip hash calculationHash calculation reads every byte of each ROM file. If you do not use RetroAchievements or other hash-based matching, you can skip it in config.yml:

filesystem:
  skip_hash_calculation: true

3. Use Quick Scan for rescansQuick Scan only processes files that are new or have changed since the last scan. Use it for routine rescans and reserve Full Scan for when you need to refresh all metadata.4. Schedule scans during off-peak hoursUse the scheduled rescan feature to run scans at night when the system is otherwise idle:

environment:
  - ENABLE_SCHEDULED_RESCAN=true
  - SCHEDULED_RESCAN_CRON=0 3 * * *

How to view logs

Live container logs

docker logs romm -f

Add --tail 100 to show only the last 100 lines:

docker logs romm -f --tail 100

Increase log verbositySet LOGLEVEL=DEBUG in your environment to enable verbose output including metadata API requests, database queries, and file scan details:

environment:
  - LOGLEVEL=DEBUG

In-app logs viewerRomM includes a built-in log viewer in the administration UI (Administration → Logs). This shows the same output as docker logs in a convenient browser-based interface. You can disable it with DISABLE_LOGS_VIEWER=true if you prefer to manage logs externally.

Library Management

Playing Games

Integrations

Operations

Troubleshooting Common RomM Problems and Solutions

Still stuck?

Build docs developers (and LLMs) love