Skip to content

Your First Scan

You're up and running (Quick Start), your ROMs are laid out correctly (Folder Structure), and metadata credentials are configured (Metadata Providers), so the next step is a first scan to catalogue everything.

Before you hit scan

Check two things first:

  • Library is mounted: on the host, ls /path/to/library should show your roms/ (or per-platform) folders. If it doesn't, the mount is wrong.
  • At least one metadata provider is configured: scans run without one, but every game comes back "unmatched" and you'll have nothing useful to look at.

Run the scan

Trigger a scan from the web UI:

  • Pick which metadata sources to query
  • Use the Quick mode for the first run
  • Start the scan

A running scan survives browser refreshes and you can leave and come back later. Per-platform progress shows counts updating live (total found, matched, unmatched), so you can dip in and inspect matched ROMs while the scan continues.

First scans on big libraries take a while: expect ~4 seconds per ROM with a fast network to IGDB/ScreenScraper, and hashing (which runs unless you disabled it) adds IO time proportional to file size.

What "matched" means

For each ROM the scanner:

  1. Computes hashes (CRC32, MD5, SHA1, plus RetroAchievements-specific hashes).
  2. Hits the configured metadata providers in priority order. First provider to recognise the file (by hash or filename) becomes the initial match.
  3. Writes the DB entry with title, cover, description, release date, and anything else the providers returned.
  4. Merges overlay data from other providers: RetroAchievements progression, HowLongToBeat completion times, SteamGridDB alternate covers if you've asked.

An unmatched ROM means no provider recognised it, with common causes:

  • Filename is too generic (game.gba)
  • Platform folder misnamed
  • Bad rip, intro/patch applied, or a regional variant no provider has indexed
  • Metadata provider credentials wrong or rate-limited

Most of these are fixable (see Scanning Troubleshooting).

When the scan finishes

Your dashboard shows a card per scanned platform plus recently-added and continue-playing rows.

Typical next steps:

  • Fix unmatched ROMs: rename or re-tag, then re-run an Unmatched scan to pick them up (see Scanning & Watcher).
  • Tweak priorities: if ScreenScraper's covers are nicer than IGDB's for your library, reorder scan.priority.artwork in config.yml.
  • Switch boxart styles: 3D boxes, physical media, or mix images on your cards need the matching media type added to scan.media and a rescan, since the UI picker alone isn't enough (see Boxart styles and media types).

Skip to a targeted scan

If you're adding ROMs later and don't want a full rescan:

  • New Platforms: only scans folders not seen before, and it's fast.
  • Quick: skips ROMs already catalogued, a good default for "I added a few games".
  • Unmatched: re-runs matching against ROMs without a provider ID, ideal after adding a metadata provider.

All six scan modes are documented in Scanning & Watcher.