Affiliate disclosure: This guide contains affiliate links. As an Amazon Associate, we earn from qualifying purchases at no extra cost to you. Learn more.

How to Fix Box Art and Scraper Problems on Retro Handhelds

Q: Why is my scraper so slow?

Most scrapers pull from ScreenScraper, which heavily throttles anonymous users. Creating a free account and entering your credentials in the scraper raises the rate limit substantially and is the fastest fix for a scrape that crawls along or times out.

Q: How do I fix box art for multi disc PS1 games?

Create an .m3u playlist file that lists the individual disc images, then point your library at the .m3u instead of the discs. This gives the scraper one clean filename to match, and it fixes in game disc swapping at the same time.

2026-07-29 · Troubleshooting

Affiliate disclosure: This guide contains affiliate links. As an Amazon Associate, we earn from qualifying purchases at no extra cost to you. Learn more.

A wall of box art is what makes a retro handheld feel like a real console instead of a file browser. It is also one of the most common things to go wrong. Scrapers miss games, grab the wrong cover, pull artwork for the Japanese version, or refuse to connect at all.

Almost every scraper problem traces back to one of four causes. Here is how to work through them.

How Scrapers Actually Work

Understanding this makes every fix obvious.

A scraper takes your game's filename, searches an online database for a match, then downloads artwork and metadata and saves it next to your game. It usually writes a gamelist.xml file that your frontend reads.

So the filename is everything. If your file is called smb3.zip, no database on earth knows what that is. If it is called Super Mario Bros. 3 (USA).zip, it matches instantly.

Fix 1: Name Your Files Properly

This solves the majority of scraper failures.

The standard the databases expect looks like this:

Super Mario Bros. 3 (USA).nes
Chrono Trigger (USA).sfc
Castlevania - Symphony of the Night (USA).chd

The rules that matter:

Use the full official title. No abbreviations, no shorthand.
Keep the region tag in parentheses, such as (USA), (Europe), or (Japan).
Use a hyphen instead of a colon. Filesystems do not allow colons, so Castlevania - Symphony of the Night is correct.
Drop release group tags. Things in square brackets confuse matching.

Renaming a large library by hand is miserable. A PC tool that renames against a known database is worth the setup time if your collection is big.

Fix 2: Scrape on a PC, Not the Handheld

This is the advice that saves people the most frustration.

Scraping on the device is slow, hammers a weak Wi-Fi chip, and often times out partway through a large library. Scraping on a computer is faster, more reliable, and easier to fix when something goes wrong.

The usual approach:

Put the microSD card in your PC.
Run a desktop scraper such as Skraper or the scraper built into ES-DE.
Let it process the whole library at once.
Put the card back in the handheld.

Our ES-DE setup guide covers its built in scraper, which is genuinely good.

Fix 3: Register for a Database Account

Many scrapers pull from ScreenScraper, which throttles anonymous users hard. If your scraper crawls along at one game per several seconds, or fails constantly, this is usually why.

Creating a free account and entering the credentials in your scraper raises your rate limit substantially. It is the single fastest fix for "the scraper works but it is unbearably slow."

Note that these databases are community run and occasionally go down or get overloaded. If a scrape fails across the board, check whether the service is having a bad day before you start changing settings.

Fix 4: Check Where the Artwork Is Being Saved

Sometimes the scrape works and the art still does not appear. That is a path problem.

Different frontends expect artwork in different folders. EmulationStation variants, ES-DE, and OnionOS all have their own conventions.
If you scraped with a PC tool, make sure its output folder matches what your frontend reads.
Check that the gamelist.xml file actually landed in the system's ROM folder.
Some frontends need a refresh, a rescan, or a restart before new artwork shows.

If artwork appears for some systems but not others, the folder structure for the missing systems is almost certainly wrong.

Fix 5: Wrong Cover, Wrong Region

If you are getting Japanese box art for a US game, or a completely different game entirely:

Add or correct the region tag in the filename. (USA) versus (Japan) genuinely changes the result.
Set a region preference in your scraper settings. Most let you prioritise US, EU, or JP artwork.
Manually override the match. Most scrapers let you search and pick the correct game for a stubborn file. For a handful of problem games this is faster than fighting the automatic matcher.

Multi disc PS1 games are a classic trouble spot. A .m3u playlist file that points to the individual discs both fixes the in game disc swapping and gives the scraper a single clean thing to match.

Fix 6: Firmware Specific Quirks

Different firmware handles artwork differently.

OnionOS on the Miyoo Mini has its own artwork system and its own expected folders. Our OnionOS guide covers it.
muOS and KNULLI both use their own catalogue structures. See the muOS setup guide and KNULLI setup guide.
Stock Anbernic firmware is usually the most limited. If artwork matters a lot to you, custom firmware is a genuine upgrade.

Quick Checklist

Rename files to the full title with a region tag
Scrape on a PC rather than the handheld
Register a free ScreenScraper account to lift rate limits
Confirm artwork is landing where your frontend looks for it
Set a region preference to stop wrong region covers
Use .m3u playlists for multi disc games
Check your firmware's specific artwork conventions

Frequently Asked Questions

Why is my scraper not finding any games?

The most common cause is filenames the database cannot match. Rename files to the full official title with a region tag, such as Super Mario Bros. 3 (USA).nes. Short or abbreviated names will not match anything.

Why is my scraper so slow?

Most scrapers use ScreenScraper, which heavily throttles anonymous users. Creating a free account and entering your credentials in the scraper raises the rate limit and speeds things up dramatically.

Should I scrape box art on my handheld or on a PC?

On a PC. It is much faster, far more reliable, and easier to troubleshoot. Put the microSD card in your computer, run a desktop scraper across the whole library, then return the card to the handheld.

Why am I getting Japanese box art for US games?

Your filenames are missing region tags, or your scraper's region preference is set wrong. Add (USA) to the filename and set your scraper to prioritise US artwork.

How do I fix box art for multi disc PS1 games?

Create an .m3u playlist file listing the individual disc files, and point your library at the .m3u instead. This gives the scraper one clean filename to match and it fixes in game disc swapping at the same time.

The scrape finished but no artwork shows up. Why?

The artwork saved somewhere your frontend is not looking. Check that the images and gamelist.xml landed in the folders your specific frontend expects, then restart or rescan. Artwork paths differ between ES-DE, OnionOS, muOS, and stock firmware.