Skip to main content
Version: Stable

Troubleshoot Frontend

Start with the symptom you see. Frontend displays the library managed by Zaparoo Core, so game discovery and artwork problems can involve either the Frontend screen or Core's media database.

First-time setup stays on Preparing​

Frontend requires Zaparoo Core v2.15.0 or newer. Some MiSTer images include an older Core build that does not support Frontend.

Update Core through Update All, then reboot MiSTer or restart Frontend. See Install and Set Up Frontend for the supported installation methods.

Games do not appear​

Run Update media database from Settings, then Library. You can also open a system's options menu and update that system on its own.

A media database update finds game files and makes them available to Frontend. Scraping metadata does not add missing games to the database.

Games appear without artwork​

Work through these checks in order:

  1. Confirm the game appears after running Update media database. Scrapers only enrich games already present in Core's database.
  2. Confirm compatible metadata and artwork files exist on the SD card, USB drive, or NAS. Core does not download artwork from the internet.
  3. Run Scrape metadata from Settings, then Library.
  4. Check that each gamelist.xml game path resolves to an indexed game and that its image paths resolve to files Core can read.

See Add Artwork and Metadata for supported sources and the complete import workflow.

Scrape actions are unavailable​

Scraping cannot start while a media database update is running. Wait for the update to finish, then run Scrape metadata.

Only one scrape can run at a time. If metadata is already being scraped, wait for it to finish before starting another one.

Updated artwork does not appear​

A normal scrape skips games that already have imported scraper metadata. Enable Re-scrape existing, then run the scrape again after replacing artwork, correcting paths, or changing metadata that was previously imported.

Arcade artwork is missing​

MiSTer Arcade games use .mra files under /media/fat/_Arcade. Use an artwork pack that explicitly includes _Arcade content or use ZapScraper's Arcade support. A console artwork pack does not necessarily include Arcade games.

See the artwork source guide for the available packs and tools.

Artwork on USB or a NAS is not found​

Metadata can sit beside games on an SD card, USB drive, or NAS share. Check that gamelist.xml game and image paths resolve to locations Core can read.

To keep metadata separate from your games, configure a custom_path and create one folder per exact system ID. Custom bundles enrich games already in the media database, so update the database before scraping.

Upload support logs​

Open Settings, then Support, then Upload log file. Frontend uploads a support bundle and shows a link you can share in Discord or a GitHub issue.

The upload includes a support summary, the Frontend log tail, and the Core log tail when Core is reachable. Include what you were trying to do, the steps that reproduce the problem, and the uploaded support link when asking for help.