The image is there and cannot be shown

The symptom

The media library shows the attachment. The file exists at the path WordPress expects. Every integrity check that only asks “is the file there?” passes. And the product page still shows a broken image, or a blank box the size of a photograph.

Three things cause it, and they look identical from the admin: the file is zero bytes or truncated because an upload was interrupted; it is a format the browser will not decode — a TIFF, a CMYK JPEG, an HEIC straight off a phone; or the intermediate sizes were never generated, so the theme asks for product-thumbnail and gets nothing.

What it costs

Exactly what a missing photograph costs, with one addition: it survives the checks you would normally run.

• The product page has a hole in it where the deciding piece of information should be. A customer who cannot see the item does not buy the item.
• It usually arrives in batches. An interrupted bulk upload, a migration that copied files but not the intermediate sizes, or a phone-camera workflow that started producing HEIC last month — each affects dozens of products at once.
• Nobody notices from the admin. The library thumbnail is often generated from a different size, or cached, so the grid looks fine while the storefront does not.

How to check it yourself

Zero-byte and unreadable files, straight from the shell:

find wp-content/uploads -type f \( -name '*.jpg' -o -name '*.png' -o -name '*.webp' \) -size -1k

Anything listed is too small to be an image. For files that are large enough but still broken, identify from ImageMagick reports on each one and fails loudly on the bad ones:

find wp-content/uploads -name '*.jpg' -exec identify -quiet {} + 2>&1 | grep -i error

Missing intermediate sizes are a database question instead — attachments whose _wp_attachment_metadata contains no sizes array were never processed by the media pipeline.

How to fix it

1. Re-upload the originals for zero-byte and truncated files. There is nothing to repair; the data is not there.
2. Convert unsupported formats to JPEG or WebP before uploading. HEIC and CMYK TIFF are the two that reach a store most often, and neither is a browser format.
3. Regenerate the intermediate sizes where the original is intact:

wp media regenerate --only-missing --yes

4. Fix the source of the batch. If a migration or a phone workflow produced these, the next batch will look the same.

When it is a false positive

• Images served by a CDN or an offload plugin, where the local file is deliberately a zero-byte stub and the real file lives in object storage.
• Formats your setup does convert on the fly — some hosts and plugins transcode HEIC or serve AVIF with a fallback, in which case the browser never sees the original.
• Attachments that are not images and were never meant to be displayed, such as a PDF manual attached to the product.

How Merchlint finds it

Merchlint takes every image attached to a published product, checks that the file exists, reads its size on disk, and reads enough of the header to confirm the format matches the extension and that the file is not truncated. It then checks _wp_attachment_metadata for the intermediate sizes the active theme actually asks for.

Known offload plugins are detected first, and their stub files are excluded — otherwise this check would report an entire CDN-backed catalogue as broken.

Confidence: F — fact from the filesystem and the database. The bytes are readable as an image or they are not.

This check ships in the Pro add-on.