KNULLI Scraped Box Art Not Showing? Fix Missing Game Images and Metadata

by

Short Answer

Diagnose one game that is already visible in KNULLI. Do not begin with a full-library scrape.

  1. Confirm KNULLI already has usable network connectivity. If it does not, fix KNULLI Wi-Fi first.
  2. Open Start → Scraper → Scraper settings.
  3. Choose a provider that is legitimately configured for your release.
  4. For a box-art test, set Box source to Box 2D and keep Overwrite medias disabled unless replacement is intentional.
  5. Hold the configured game-launch button on one visible game, then choose Scrape.
  6. If there is no match, choose Input and search for a clean or international title. Do not rename the ROM during diagnosis.
  7. Accept the correct title, system, and region result.
  8. With the default Art-Book-Next theme, set Game Artwork to Boxart.
  9. Run Start → Game Settings → Update gamelists once.
  10. Verify the text metadata and box image separately.

“Scraping finished” does not prove that the game matched, that the requested media existed, that its download was written, or that the selected theme displays that media field.

Version and evidence scope

  • Devices: RG CubeXX and relevant H700 KNULLI builds
  • Releases: Firefly 20241204, Gladiator II 20250813, Scarab 20260511
  • Storage paths: Logical /userdata paths; the active storage device supplies /userdata
  • Frontend evidence: Scarab is pinned to an exact KNULLI EmulationStation revision; Firefly and Gladiator II use near-release official snapshots because their package recipes tracked a moving branch
  • Method: Official documentation and source; no owner-device outcome is claimed

Symptom: Keep These Six Problems Separate

A. The scrape does not start or shows a provider/authentication error

This is the network, provider, account, API-key, quota, or request stage. It is not an image-display problem.

B. The scrape runs but finds no match

The request reached the search stage, but the provider did not identify the game. Use the single-game Input search before changing any filename.

C. Metadata text updates but the image does not

Metadata and media are separate. A result can update title or description even when the requested image is absent or its download/write fails.

D. Media is downloaded but the selected theme or view does not display it

The active theme may be rendering Image source while the scraper saved Box source, or vice versa. A file on storage is not proof that the current view uses that media field.

E. Some games or systems are skipped

Bulk filters, selected systems, recent-scrape exclusion, no-match results, and provider coverage can all create partial results.

F. Results appear only after Update gamelists

This is a frontend-refresh stage. Use the supported Update gamelists action instead of rebooting or rebuilding the library.

Version Scope

Firefly 20241204

Firefly officially added RG CubeXX support and ships a device-specific H700 image.

Its package recipe followed the moving knulli frontend branch rather than pinning an immutable frontend commit. The nearest official source snapshot shows the same core scraper menu, providers, filters, per-game Scrape, manual Input, and Update gamelists workflow found later.

No tagged Firefly scraper-specific change is documented. Treat historical English labels as high-confidence equivalents, not proof that every Firefly language, theme, or image used character-for-character current wording.

Gladiator II 20250813

Gladiator II continues RG CubeXX support. Its package recipe also followed a moving frontend branch; the nearest official pre-release snapshot shows the same scraper settings and start flow.

The release updated the bundled Art-Book-Next and ES-Knulli themes and filtered KNULLI-compatible themes. Theme rendering can therefore differ from Firefly even when scraped media paths are unchanged.

Scarab 20260511

Scarab includes an official H700 RG CubeXX image and revised H700 support. Its package pins exact frontend commit 4041b56a714265de81de8165b34fbd10f313a891, so current menu labels and behavior are source-pinned.

Scarab also adds:

  • a user-facing TheGamesDB API key field;
  • no TheGamesDB request when that key is empty;
  • scraper start/stop hooks that pause and resume battery-saving behavior during a scrape.

Those Scarab behaviors must not be generalized backward to Firefly or Gladiator II.

Identify the Failure Stage

Before changing settings, record the exact result for one game:

  • Does the UI show Scrape failed or a named provider/account problem?
  • Does it show No games found?
  • Does it show one or more provider matches?
  • After accepting a match, does text metadata change?
  • Is an image visible only after changing the theme field?
  • Does the result appear only after Update gamelists?

These observations locate the failure stage:

  1. Request/provider/authentication
  2. Game identity and search
  3. Media availability/download/write
  4. Theme/view rendering
  5. Filter or system selection
  6. Gamelist refresh

Do not treat a working network connection as proof that a provider accepted the request or that account configuration is valid.

Confirm Provider and Authentication

KNULLI supports three scraper providers in the documented/current frontend:

  • ScreenScraper
  • TheGamesDB
  • ArcadeDB

Open:

Start → Scraper

The source selected there is used for multi-game scraping. Single-game scraping can search available sources and group results by provider.

Providers do not share identical account, API-key, quota, system, or media behavior. Configure only the provider you intend to use for the one-game test.

ScreenScraper

KNULLI documentation requires a ScreenScraper account and exposes username and password fields under Scraper settings.

Enter your own credentials only on the device. Do not post, screenshot, or share them.

ScreenScraper enforces request quotas, including negative-result limits. If the provider reports authentication, maintenance, blacklist, or quota failure, stop repeated retries and resolve the issue through the provider’s legitimate process. Do not create extra accounts or launch a bulk scrape to bypass a limit.

TheGamesDB on Scarab

Scarab’s pinned frontend shows:

ACCOUNT → API KEY

When TheGamesDB is selected, the Scarab source does not generate a request if this field is empty.

Use your own legitimate API key or select another provider you are configured to use. Do not invent, request from strangers, publish, or share an API key.

TheGamesDB documentation conflict

Current KNULLI prose explicitly discusses ScreenScraper credentials but does not yet explain Scarab’s TheGamesDB key requirement.

Older Firefly/Gladiator-era source used a KNULLI build-time TheGamesDB key. Scarab changes this to a user-entered key. Preserve that as a release-specific documentation/source discrepancy rather than applying the Scarab requirement to older releases.

ArcadeDB

ArcadeDB remains one of the registered providers. Do not assume its coverage, media, or account behavior is identical to ScreenScraper or TheGamesDB.

Diagnose No Match

A no-match result is an identity/search problem, not proof that images cannot be displayed.

KNULLI’s scraper uses the ROM or script filename and may consider region markers. Unusual or poor names can prevent automatic identification.

Use the supported one-game path:

  1. Choose a game that is already visible in KNULLI.
  2. Hold the configured button that normally launches it to open its game menu.
  3. Select Scrape.
  4. If the result says No games found, choose Input.
  5. In Search for, enter a clean or internationally recognized game title.
  6. Review results grouped by provider.
  7. Select the correct platform, title, and region.

Do not hard-code a South or East button name; the launch-button convention can differ with configuration.

Do not rename the ROM or script during diagnosis. Some systems require exact filenames, and renaming is not a universal match fix.

A successful manual match proves that the provider resolved that search. It does not yet prove that the requested image exists, downloaded successfully, or will render in the active theme.

Check Media and Metadata Write

Open:

Start → Scraper → Scraper settings

Relevant settings include:

  • Image source
  • Box source
  • Logo source
  • Preferred region or the displayed build equivalent
  • Overwrite descriptions
  • Overwrite medias

Choosing None for an image or box field means that field is not requested.

For a deterministic box-art check:

  1. Set Box source to Box 2D.
  2. Choose the expected region.
  3. Keep Overwrite medias disabled unless you intentionally want to replace existing art.
  4. Scrape the one selected game again.
  5. Accept a result that matches the title, system, and region.
  6. Wait for that result’s media operation to finish.

Do not enable mass overwrite during diagnosis.

Text can update without an image

In the Scarab media resolver, a new media path is recorded only after a nonzero file is written. A selected provider result may also lack the requested image type.

This means title, date, or description can update while artwork remains absent. Do not infer “storage is full” from missing art alone.

Investigate free space or writability only when KNULLI reports a file-stream/write failure or the device independently shows insufficient space.

Logical /userdata paths

KNULLI stores user data under logical /userdata.

  • In a single-card setup, /userdata points to SD1’s SHARE partition.
  • In an active dual-card setup, /userdata points to SD2’s main partition.
  • Only the selected active storage supplies /userdata.

When the active card is uncertain, verify which second SD card backs /userdata.

Do not assume scraped files are always on SD1 or always on SD2.

For a standard system root such as /userdata/roms/snes, the normal paths are:

  • Metadata references: /userdata/roms/snes/gamelist.xml
  • Scraped images: /userdata/roms/snes/images/
  • Videos: /userdata/roms/snes/videos/
  • Manuals: /userdata/roms/snes/manuals/

The frontend builds media filenames from the ROM stem and media suffix, then stores the reference in the gamelist.

These are normal system-root paths, not the only internally possible gamelist location. The source has a fallback when an existing EmulationStation configuration gamelist is used.

Do not edit XML, change paths manually, or delete gamelist/media folders for this diagnosis.

Check the Theme or View Media Field

A successful download and a visible image are different checks.

Current KNULLI’s default Art-Book-Next theme can show either the scraper’s Image field or Box field as game artwork.

Open:

Start → User Interface Settings → Theme Configuration

Then match the display field to the source you scraped:

  • Game Artwork: Boxart uses Box source.
  • Game Artwork: Image or Image (Cropped) uses Image source.
  • Game Metadata controls text display independently.

For the Box 2D verification in this guide, choose Game Artwork → Boxart.

If metadata text is also hidden, turn Game Metadata on so it can be verified separately.

Third-party and historical themes may not expose or render the same fields. If the image appears under Art-Book-Next with the matching field but not under another theme, the leading issue is theme/view compatibility—not a reason to delete or scrape the media again.

Gladiator II updated bundled themes, so presentation differences between Firefly and Gladiator II do not imply that storage paths changed.

Check Filters and Skipped Games

Bulk scraping can intentionally omit entries through:

  • Games to scrape for: All
  • Games missing any media
  • Games missing all media
  • Ignore recently scraped games
  • Systems included

A completed run does not prove that every game matched.

The frontend can record a scrape date even for a no-result item. Ignore recently scraped games may therefore skip a recent no-match on the next bulk attempt.

For diagnosis, bypass the bulk filters:

  1. Open the menu for one skipped visible game.
  2. Select Scrape.
  3. Record whether it produces a provider error, No games found, or valid matches.
  4. Use Input if needed.

Do not start another library-wide Scrape now while the one-game result is unresolved. Repeated bulk retries can consume provider quota without correcting a bad identity or display field.

Run the Supported Update Gamelists Action

After accepting the one-game result, run:

Start → Game Settings → Update gamelists

Confirm the prompt once, then return to the selected system and game.

The frontend reloads the game lists through this supported action. KNULLI documentation and the source-backed flow do not require a reboot as the first refresh step.

A result that appears only after Update gamelists indicates that the stored references needed a frontend reload. It does not prove that every media path in the library is valid.

Do not use Clean Gamelists & Remove Unused Media during diagnosis. Do not rebuild, delete, or regenerate the entire library.

One-Game Verification

Use one well-known game that is already visible and legally owned.

1. Confirm the bounded prerequisites

  • KNULLI has usable connectivity.
  • The game is already visible.
  • The exact KNULLI release is known.

Stop if those prerequisites are not met. This article does not repair Wi‑Fi, SMB, ROM discovery, BIOS, or game launching.

If the game itself is not visible, make a copied game appear in KNULLI before troubleshooting artwork.

2. Configure one provider and one media type

Open Start → Scraper → Scraper settings.

  • Choose a provider that is legitimately configured.
  • Set Box source to Box 2D.
  • Set the expected region.
  • Leave Overwrite medias protected unless replacement is intentional.

3. Scrape one game

Hold the configured launch button on the game, choose Scrape, and classify the result.

  • Provider/auth failure: stop at the provider stage.
  • No match: use Input and search the clean/international title.
  • Valid matches: choose the correct platform, title, region, and provider result.

Wait for the selected result to finish. Do not start a bulk job.

4. Match the default theme field

Open:

Start → User Interface Settings → Theme Configuration

Set:

  • Game Artwork → Boxart
  • Game Metadata → On

This verifies the Box source and text metadata independently.

5. Refresh once

Run:

Start → Game Settings → Update gamelists

Return to the same game.

6. Pass condition

Verify both:

  1. The intended title, description, date, or another selected metadata field is visible.
  2. The expected Box 2D image is visible in the Boxart presentation field.

The two checks are separate. A pass shows that the provider returned the selected match, the chosen data was incorporated into the active frontend state, the supported refresh completed, and the tested theme field can render it.

It does not prove that every game or system will match, every media type exists, bulk filters include everything, or a third-party theme behaves the same.

Version Differences at a Glance

Release Frontend source certainty Material scraper difference
Firefly 20241204 Near-release official snapshot; package tracked a moving branch Same core workflow; no tagged scraper-specific change documented
Gladiator II 20250813 Near-release official snapshot; package tracked a moving branch Bundled Art-Book-Next and ES-Knulli themes updated, so presentation can differ
Scarab 20260511 Exact frontend commit pinned User TheGamesDB API key required for TheGamesDB requests; scraper battery-saving pause/resume hooks added

The logical /userdata media paths remain the same workflow across the supported frontend lineage. Do not use the Scarab API-key field or battery hook to describe older releases.

If It Still Fails

A. Scrape does not start or shows provider/authentication failure

  • Confirm only that KNULLI has usable connectivity.
  • Identify the selected provider.
  • For ScreenScraper, use your legitimate account entered privately on-device.
  • On Scarab with TheGamesDB, confirm your legitimate API key field is not empty.
  • Record the exact UI result without exposing credentials.
  • If the provider reports quota, maintenance, blacklist, forbidden, or authentication failure, stop repeated retries.

Do not bypass quota, create extra accounts, share credentials, or claim a working network proves provider success.

B. Scrape runs but finds no match

  • Scrape the one game directly.
  • Choose Input.
  • Search the clean or international title.
  • Select the correct system and region result.
  • Leave the ROM or script filename unchanged during diagnosis.

C. Text metadata updates but image does not

  • Confirm Box source or Image source is not None.
  • Match the expected region.
  • Re-scrape the one game and inspect whether the chosen result offers the requested media.
  • Keep overwrite protected unless replacement is intentional.
  • Investigate storage only when a write/file-stream error or independent free-space evidence exists.

Do not claim metadata success proves an image was downloaded.

D. Media exists but the theme does not show it

  • Under Art-Book-Next, select Boxart for Box source or Image for Image source.
  • Turn Game Metadata on to check text separately.
  • Use the default theme as a presentation test when a third-party theme differs.

Do not delete or re-scrape media before checking the presentation field.

E. Some games or systems are skipped

  • Inspect Games to scrape for.
  • Inspect Ignore recently scraped games.
  • Inspect Systems included.
  • Bypass those bulk filters with a one-game Scrape.

A finished bulk job is not proof that every item matched.

F. Results appear only after refresh

  • Run Start → Game Settings → Update gamelists once.
  • Return to the same system and game.
  • Verify metadata and image separately.

Do not reboot, reflash, rebuild, or delete gamelist/media folders as a refresh method.

Preserve evidence without exposing secrets

If escalation is needed, record locally:

  • KNULLI release;
  • provider name;
  • one game title;
  • exact stage: failed request, no match, missing media, theme display, filter, or refresh;
  • selected media field and region;
  • selected theme/view;
  • exact error wording.

Do not include usernames, passwords, API keys, email addresses, provider account screens, Wi‑Fi data, IP addresses, or a full unredacted library list.

Do not factory-reset, reflash, update, downgrade, format storage, mass-rename ROMs, move libraries in bulk, edit XML, delete media folders, or enable mass overwrite for this workflow.

FAQ

Which scraper providers does KNULLI support?

Current KNULLI registers ScreenScraper, TheGamesDB, and ArcadeDB. Their authentication, quota, media, and system coverage are not identical.

Why does TheGamesDB fail on Scarab when older KNULLI releases worked?

Scarab’s pinned source requires a user-entered TheGamesDB API key and generates no request when it is empty. Older Firefly/Gladiator-era source used a build-time key. Current KNULLI prose has not fully documented this change.

Why did the title and description update but not the picture?

The provider result may not include the requested media, the media download/write may have failed, or the theme may be displaying a different field. Check Box source/Image source, then match Game Artwork to that field.

Does a file under the images folder prove KNULLI will display it?

No. The gamelist must reference it, and the active theme/view must render that media field.

Where does KNULLI normally store scraped images?

For a standard system rooted at /userdata/roms/<system>, images normally go under /userdata/roms/<system>/images/, with references in the system’s gamelist. The source can use a fallback gamelist path when an existing configuration gamelist is present.

Should I delete gamelist.xml and scrape again?

No. Use one-game scraping, theme-field checks, and Update gamelists. Deleting the gamelist or media folders is destructive and unnecessary for this diagnosis.

Why were some recently failed games skipped on the next bulk scrape?

A no-result item can still receive a scrape date. Ignore recently scraped games may then skip it. Diagnose that entry directly with one-game Scrape and Input.

Do I need to reboot after scraping?

No reboot is required by the supported refresh flow. Run Start → Game Settings → Update gamelists when the result does not appear.

Sources

KNULLI documentation and storage

Release and frontend scope

Scraper providers and account behavior

Single-game search, filters, media, and refresh