From 7bbbbaf64020e50220c65a6e728ced57642b5c1a Mon Sep 17 00:00:00 2001 From: Georges-Antoine Assi Date: Wed, 19 Aug 2026 14:54:54 -0400 Subject: [PATCH] docs: document ScreenScraper developer credentials RomM sends ScreenScraper developer (application) credentials alongside the user credentials on every request. They're injected at image build time, so installs that don't use our official image (builds from source, third-party packages like the new nixpkgs one) send empty values and get a 403 that surfaces as "401: Invalid ScreenScraper credentials". Explain the second credential pair in the ScreenScraper setup section and add a scanning troubleshooting entry with the actual log lines, so the misleading error message is searchable. Reported in https://github.com/NixOS/nixpkgs/pull/547607 Co-Authored-By: Claude Opus 5 (1M context) --- docs/getting-started/metadata-providers.md | 6 ++++++ docs/troubleshooting/scanning.md | 11 +++++++++++ 2 files changed, 17 insertions(+) diff --git a/docs/getting-started/metadata-providers.md b/docs/getting-started/metadata-providers.md index 1544ed42..6731c198 100644 --- a/docs/getting-started/metadata-providers.md +++ b/docs/getting-started/metadata-providers.md @@ -73,6 +73,12 @@ Note the client ID and secret that appear on screen, and use them to set `IGDB_C To access the ScreenScraper API, create a [ScreenScraper](https://www.screenscraper.fr/membreinscription.php) account and copy the **user** and **password** you just created to `SCREENSCRAPER_USER` and `SCREENSCRAPER_PASSWORD` respectively. +ScreenScraper's API also expects a second pair of **developer** credentials that identify the calling application, which RomM sends on every request alongside your user credentials. Our official Docker images have RomM's developer credentials baked in at build time, so there's nothing extra to set. + + +!!! important "Running RomM outside our official image" + Builds from source and third-party packages (such as the `romm` package in nixpkgs) ship without developer credentials, and ScreenScraper then rejects every request with `403 Forbidden`, which the scanner reports as `401: Invalid ScreenScraper credentials` even when `SCREENSCRAPER_USER` and `SCREENSCRAPER_PASSWORD` are correct. Set `SCREENSCRAPER_DEV_ID` and `SCREENSCRAPER_DEV_PASSWORD` to a valid developer pair to fix it. ScreenScraper issues developer credentials to registered members on request, and the pair inside our official images is also usable. Either way, load them from a secret store or an env file rather than a world-readable config, and never commit them. Nothing else in RomM depends on them, so every other provider and feature keeps working while they're unset. + ### MobyGames MobyGames is a metadata provider that offers metadata, cover art and screenshots. diff --git a/docs/troubleshooting/scanning.md b/docs/troubleshooting/scanning.md index 4bb8e18f..91dae82a 100644 --- a/docs/troubleshooting/scanning.md +++ b/docs/troubleshooting/scanning.md @@ -80,6 +80,17 @@ Options, in order of effort: 2. **Use filename tags**: if you already know the provider ID, rename the file to include `(igdb-1234)` or similar (see [Metadata Providers → Filename tags](../getting-started/metadata-providers.md#metadata-tags-in-filenames)). 3. **Manually match**: open the ROM detail page, click the **Match** button, and search for the right title. +## ScreenScraper fails with 403 Forbidden + +```text +ERROR: [RomM][screenscraper] 403, message='Forbidden', url='https://api.screenscraper.fr/api2/jeuInfos.php?...' +ERROR: [RomM][scan] 401: Invalid ScreenScraper credentials +``` + +Despite the message, this usually isn't your account. ScreenScraper also requires developer credentials identifying the application, which our official Docker images supply at build time and builds from source or third-party packages don't, so set `SCREENSCRAPER_DEV_ID` and `SCREENSCRAPER_DEV_PASSWORD` and rerun the scan (see [ScreenScraper](../getting-started/metadata-providers.md#screenscraper)). + +If you're on an official image and still get 403s, re-check `SCREENSCRAPER_USER` and `SCREENSCRAPER_PASSWORD`, then check whether you've exhausted your account's daily request quota. + ## Hash calculations are slow Hashing large ROMs (PS1, Saturn, DC images) is IO-bound, with a few options: