If a WordPress original image opens but its thumbnail is broken, inspect the exact smaller file requested by the browser. The problem may be a missing derivative, an outdated size reference, or offload storage that never received the generated file. Regenerating every image is rarely the best first test.
Capture the failed size
Use browser developer tools to inspect the broken image request. Record the URL, status, and response type. Responsive images can select different files at different viewport widths, so compare the requested source on desktop and mobile rather than only reading the image's basic src attribute.
Open the original from its Media Library record. If that also fails, investigate missing media after a restore. Thumbnail generation cannot reconstruct an original that no longer exists.
Compare three records
Identify the attachment ID, its stored image-size metadata, and the actual files in local or remote storage. A filename such as photo-300x200.jpg suggests dimensions but does not prove which registered size generated it.
| Evidence |
Interpretation |
| Original and metadata exist, derivative absent |
Generation or storage synchronization needs review |
| Requested size absent from current configuration |
Theme or plugin may reference an obsolete size |
| Derivative exists but returns 403 |
Fix delivery permissions before regeneration |
| Different image appears at the same URL |
Investigate replacement and cache behavior |
Requested resource: Record the actual responsive image URL. Original available: Generation cannot recover a lost source. One attachment: Back up and test before a library-wide run. Public delivery: Verify crop, bytes, and narrow/wide views. Explanatory checklist, not a customer test result.
Regenerate one attachment first
Back up the original, attachment metadata, and current derivatives. Confirm disk capacity and run the test on staging when the image-processing setup is uncertain. With WP-CLI, a developer can regenerate a known attachment while retaining existing thumbnails:
wp media regenerate 123 --skip-delete
Replace 123 with the affected attachment ID and use the correct site's command context. The command writes image files and metadata; it is not a read-only diagnostic. Do not add a library-wide flag until the one-image test works.
The only-missing option is useful for appropriate missing-size cases, but do not assume it checks every remote object that metadata already lists. Verify the resulting bytes and public URL. An offload integration may require its own synchronization step.
Resolve the reason generation failed
If one-image generation fails, read the processing error and check the PHP image extension, memory budget, source dimensions, and filesystem access. Our image upload diagnostic guide separates processing failures from rejected requests.
If the source is smaller than a requested crop, confirm whether that derivative is expected to exist under the current image-size rules. Enlarging a small original is not a reliable quality fix. For an obsolete size, repair the template's reference instead of repeatedly creating files nobody should request.
Close the loop at the browser
Purge only the affected image or page cache as needed. Recheck the actual selected image at narrow and wide widths, including high-density screens where possible. Confirm the correct crop and dimensions, not just a successful status.
Only then plan a monitored batch for other affected IDs. Keep old derivatives that external pages still reference until their use has been assessed. Get help repairing the media pipeline if metadata, remote storage, and generated files disagree.
Reference: WP-CLI media regenerate options.
References reviewed October 2, 2026. Examples are explanatory; production changes require an appropriate backup and authorized access.