Find & fix broken product images
Over time, product images rot: a local file gets pruned, a supplier takes down a hotlinked URL, a CDN path changes. A broken primary image is the one that hurts — it shows as a placeholder on the product, on packing slips, and anywhere the catalog is surfaced. SKU.io ships a two-part tool to find and clean these up: an on-demand image health check that re-validates every image, and a Broken Product Images report that lists the confirmed-broken ones so you can delete the dead images or clear false positives.
The design is deliberately cautious. The health check only flags an image broken when it's definitively gone; anything ambiguous (a host blocking automated traffic, a timeout, a server hiccup) is left alone. The report then loads each flagged image live in your browser as the final tie-breaker — images that actually render clear themselves automatically.
Before you begin
- You need read/write access to Products to run the health check and to delete or clear images. See the product permissions reference.
- The health check runs as a background job. You watch its progress in the job tray (the progress tray at the bottom of the screen) and can cancel it there.
- For adding, reordering, and setting a primary image on an individual product, see Add & manage product images.
Run the image health check
The health check re-validates every product image in your catalog and records the result on each image. Run it before working the report so the report reflects current reality.
You can start it from either place:
- Open the Product Data Health dashboard and, in the Image Health card, click Check Image Health. Or, from the report itself, click Re-check All Images.
- The check dispatches as a background job named Check Image Health. Watch it in the job tray.
- As it runs, the job reports live counts:
- images checked — total images processed so far
- images resolvable — confirmed OK this run
- images broken — confirmed definitively gone
- products with broken primary image — products whose primary image came back broken
- When it finishes, the job summary reads
Checked N images — M broken. The dashboard's broken-image count and last-checked timestamp refresh automatically, and the report reloads.
Notes and edge cases:
- It's cancellable. Cancel from the job tray and the sweep stops at the current chunk; images already checked keep their fresh result.
- Large remote catalogs are slow. Remote images are checked one at a time with deliberate pacing, so the run gives up after 30 minutes and doesn't retry on its own. If it's cancelled or times out, run it again.
- It has no side effects on your products. The sweep writes each result directly to the image row and never triggers the usual image-save behavior — it won't reset which image is primary and won't re-queue packing-slip prints.
Work the Broken Product Images report
The report lists only images the health check confirmed broken — those with a check timestamp and a broken flag. Open it from the Products with Broken Image tile on the Product Data Health dashboard (the tile is clickable once at least one health check has run), or go directly to Reports → Broken Product Images.
The report is paginated (25 per page by default; you can switch to 10 or 50). Each row shows:
| Column | What it shows |
|---|---|
| Image | A live thumbnail — the browser attempts to load the real image URL |
| Browser Check | Checking…, then Loads — cleared (self-healed) or Failed to load |
| Product | The product SKU (links to the product detail page) and name |
| Image URL | The image's URL, with copy-to-clipboard and open-in-new-tab buttons |
| Primary | Whether this is the product's primary image |
| Last Checked | When the health check last validated this image |
The browser load is the final tie-breaker
The server's probe is conservative and can produce false positives — a host that blocks automated requests may render fine in a real browser. So the report re-tests every flagged image the honest way: it loads the actual image in your browser.
- A thumbnail that loads proves the image still works. That row is marked OK automatically and drops off the list — no action needed. A running tally of these appears as an auto-cleared chip.
- A thumbnail that fails to load is genuinely broken and shows a broken-image icon. These are the rows worth cleaning up.
Because the report clears false positives as you view them, the on-screen broken count ticks down while you work.
Bulk-delete confirmed-broken images
Once the browser check has separated the genuinely dead rows from the false positives, remove the dead ones:
- Select the failed rows. Use the row checkboxes, or click Select all failed to select every row whose thumbnail failed to load on the current page.
- Click Delete Selected.
- Confirm in the dialog.
You can also delete a single row with its row-level delete button.
What deletion does:
- Removes the image from its product. Deletion goes through the full image-delete path: the server-stored file (for local images) is removed, and the parent product's primary image is reset if you deleted its primary.
- Re-queues packing slips. If a deleted image affected a product's primary image, affected packing slips are re-queued so reprints use the corrected image.
- Limit: 500 images per action. If you need to remove more, delete in batches. Every selected image must still exist — if one was already removed, the action reports that one or more selected images no longer exist.
Mark false positives as OK
If a row is a false positive that the automatic browser check didn't clear on its own — for example, you confirmed the image loads by opening its URL in a new tab — you can clear it manually:
- Select the rows.
- Click Mark as OK.
This clears the broken flag so the image no longer counts against the product and drops off the report. Edge cases:
- It's re-verified first. Marking OK doesn't blindly trust your click. SKU.io re-checks each selected image and refuses to heal any that's definitively gone — an empty URL, a missing local file, or a remote address whose host reports the image no longer exists. Everything else (blocks, throttles, timeouts, host errors) counts as ambiguous and does heal, because a browser routinely loads images an automated check can't. Only the images that pass re-verification are cleared, so the "marked" count can be lower than the number you selected.
- Limit: 500 images per action.
How images are classified: Broken vs OK vs unknown
Understanding the three outcomes explains why a URL you think is dead sometimes isn't flagged, and why the report re-checks in your browser.
The health check validates each image against its storage type:
- Local images (a file on your tenant's image storage) are checked authoritatively and cheaply — the file either exists on disk or it doesn't.
- Remote images (a full external URL) are fetched from their host. SKU.io first asks the host whether the image is there, and if the answer is inconclusive, pulls just the opening bytes of the file to confirm it really is an image. The check identifies itself like an ordinary browser and spaces its requests out, so it slips past the common hotlink and bot protections that would otherwise reject it.
The outcome is one of three:
| Outcome | Meaning | When it happens |
|---|---|---|
| OK (resolvable) | The image is confirmed present | Local file exists; remote URL returns an image (confirmed by content type or magic bytes) |
| Broken | The image is definitively gone | Empty URL, missing local file, or a remote host that reports the image no longer exists |
| Unknown (unchanged) | Can't tell — left as-is | The host refused the request, throttled it, hit an error of its own, timed out, or couldn't be reached at all — an access or availability problem, not a missing image |
Broken is reserved for a definitive "gone." A refused request or a timeout is not treated as broken, because hotlink and bot protection routinely blocks automated requests for images that load perfectly in a browser. Those stay unknown and their flag is left untouched — only the check time is updated. This is why the report's live browser load is the authoritative tie-breaker for anything the automated check couldn't confirm.
The per-host circuit breaker
If a single remote host returns a run of ambiguous failures (8 in a row), the check stops probing that host for the rest of the run and treats its remaining images as unknown. A whole host going dark mid-sweep is that host defending itself against bulk automated traffic — not thousands of its images dying at once. The circuit breaker is what prevents one hostile host from mass-flagging its entire catalog as broken.
Why the flag needs the health check
Two things are tracked on every image, and knowing how they behave explains why running the check matters:
- The broken/OK flag. It starts at OK on a new image and is never re-evaluated by an upload alone. Uploading or editing an image doesn't, by itself, confirm the URL still works.
- When it was last checked.
A product is counted as having a broken primary image only when all three hold: the image is the product's primary, its flag isn't OK, and it has been checked at least once. Requiring that last check is what stops never-checked images from being counted as broken purely because of a default.
Because the flag is never touched on upload, it drifts out of date in two ways — and the health check is what corrects both:
- Dead-URL-still-OK — an image whose URL died after upload but still reads OK. The check re-probes it and flips it to broken.
- Fixed-URL-stuck-broken — an image that was broken, then fixed, but stayed flagged broken. The check re-probes it, confirms it loads, and clears the flag.
Each run rewrites the flag with the fresh result and stamps the check time, keeping the report and the dashboard's broken-image count honest. Run the check on a schedule (or before a big catalog review) rather than assuming a one-time sweep stays accurate.
Next steps
- Add & manage product images — upload, reorder, and set a primary image on a product.
- Review the Product Data Health dashboard — where the image-health counts live alongside other catalog-quality metrics.
- Product detail page reference — the Images tab and everything else on a product.
Video transcript
The Broken Product Images report lists every image the health check flagged as unresolvable. Re-check All Images re-runs the check. Each thumbnail loads live in your browser — one that appears still works and clears itself; one that fails is genuinely broken. Here CD-WMS-1L's image failed to load — the URL is dead. The row shows the product, the image URL, and when it was last checked. Select the broken rows and Delete Selected to remove the dead images from their products.