WordPress Images and Media: Diagnose Featured Images, Broken Files and Media Library Problems

WordPress image problems can come from three different layers: the Media Library, the attachment itself, or the theme/template that displays the image. A missing featured image, a broken front-end image, and a blank Media Library grid may look related, but they require different checks.

Quick diagnosis

Featured image missing only on posts or cards: confirm an attachment is assigned as the post thumbnail and that the theme/template actually outputs it.
Broken image on the front end: inspect the image URL, generated size, cache/CDN response, permissions, and whether the file exists.
Media Library blank or stuck: check browser JavaScript, REST/AJAX requests, caching, admin conflicts, and attachment records before changing file permissions.

Featured images depend on both assignment and theme support

WordPress treats featured images as post thumbnails. The theme must support post thumbnails, the post must have an attachment assigned, and the template must call the featured-image output when that image is expected to appear.

If the image appears in the editor but not on the public page, check the template or theme layout before re-uploading the file. If the image is missing only from archive cards, the single-post template may be fine while the archive template uses a different image size or does not output the thumbnail.

Image sizes can create a display problem even when the original file exists

WordPress generates several image sizes when media is uploaded, and themes can register additional sizes. A page may therefore request a resized file rather than the original upload.

If one size returns 404 while the full-size image works, check whether that derivative size exists and whether a theme or plugin recently changed registered image dimensions. Changing thumbnail dimensions does not automatically recreate every old derivative file.

Broken front-end images need URL and response checks

Open the failed image in a new tab and inspect the exact URL. Then check the HTTP response and whether the path matches the expected uploads directory.

Common causes include:

an old domain or staging URL saved in content,
HTTP image URLs on an HTTPS page,
a missing generated thumbnail size,
CDN or optimization rewrites pointing to a stale file,
deleted media files,
and permissions or storage problems that prevented the file from being written.

A blank Media Library grid is often an admin request problem

If files still exist in wp-content/uploads but the Media Library does not display them, use the browser Network panel and console while opening the grid. Look for failed REST API or AJAX requests and JavaScript errors.

Temporarily test recently changed media, optimization, security, and admin-related plugins. Clear relevant cache layers after correcting the underlying request failure.

Responsive image markup can expose stale derivatives

WordPress adds responsive-image attributes such as srcset and sizes to generated image markup. This is normally helpful, but a stale or missing derivative can make one viewport request a different file from another.

If the image works on desktop but fails on mobile, inspect which URL the browser actually selected from srcset.

Safe troubleshooting order

Confirm whether the problem is editor-only, Media Library-only, or front-end-only.
Open the actual image URL and check its response.
Confirm the original file and expected derivative sizes exist.
Check whether the post has a featured image assigned.
Check the theme/template output and requested image size.
Inspect browser console and Network requests for Media Library failures.
Test image/CDN/cache/security plugins changed recently.
Regenerate image sizes only when the size configuration actually changed or files are missing.

Official references

Bottom line: first identify whether the failure is the media file, the attachment record, the generated image size, the Media Library interface, or the theme template. Fixing the correct layer is faster and safer than re-uploading images or changing permissions without evidence.