A broken image is more than a blank space. It can make a service page look unfinished, remove visual context from an article, or leave a visitor unsure what a product or portfolio example is supposed to show. The cause might be as simple as an outdated link—or as complicated as a missing generated image size after a migration.
The safest repair starts with identifying which layer is failing. Is the original image missing? Is the WordPress block pointing to the wrong attachment? Is an optimized version unavailable? Or does the image load correctly but display poorly because of the layout? Work through the checks in order instead of uploading duplicates immediately.
Identify exactly what is broken
Open the affected page on a normal browser window and a phone-width viewport. Note whether the image is completely missing, replaced by a broken-image icon, blurry, unexpectedly cropped, or not visible until the page moves. Those symptoms suggest different remedies.
- Broken icon or empty image: inspect the actual image URL and server response.
- Image exists but is blurry: check which source and resolution the browser selected.
- Unexpected cropping: inspect image styles, object-fit, and container aspect ratio.
- Image loads only sometimes: investigate cache, optimization, lazy loading, and request errors.
- Image visible in editor but absent publicly: compare saved block content with rendered markup.
Check the image address before changing WordPress
Right-click the affected image or inspect the element and copy its exact URL. Open that URL directly in a private browser window. If it returns a not-found response, verify whether the file was moved, renamed, deleted, or referenced with the wrong path. A file that exists in the Media Library does not guarantee that a particular outdated URL still resolves.
Look carefully at the domain, upload year and month, filename spelling, extension, and any size suffix. An old JPG reference will not automatically work merely because a newer WebP file has a similar name. Likewise, a staging-domain URL can remain embedded in the post after a site migration.
Use the actual browser request as evidence
Browser developer tools can show the requested image URL and its response status. That helps separate a genuine missing file from an image hidden by CSS or blocked by a script.
Confirm the media item exists
In WordPress, open Media Library and locate the intended attachment. Check its file URL, dimensions, alternative text, and whether it is still assigned to the correct content. If the original file is missing but a backup contains it, restoring the intended original may preserve existing links better than inserting a different image.
If the Media Library has several visually identical copies, do not delete any until you know which pages reference them. Deleting the wrong attachment can create additional broken images. Keep a record of the original URL and attachment identifier before changing anything.
Inspect responsive image sources and generated sizes
WordPress can offer different image sizes through srcset and sizes. On a desktop browser, a large file may be selected; on a phone, a smaller derivative may be requested. That means the same article can appear correct at one width and broken at another.
Inspect the image element for src, srcset, sizes, width, and height. Verify that the candidate selected by the browser actually responds. After a theme change or migration, generated intermediate sizes may need regeneration through a supported WordPress workflow. Do not manually fabricate size-specific filenames: confirm that the files really exist.
Preserve aspect ratios and meaningful alt text
The HTML width and height should match the real intrinsic proportion or a correctly generated derivative, allowing browsers to reserve space before loading. CSS can scale the displayed dimensions, but the saved dimensions should not be invented. Alternative text should communicate the image’s purpose when it conveys information; decorative images may appropriately use empty alt text.
Repair the block, not just the appearance
Reconnect the correct Media Library attachment
If the source file exists but the editor references an obsolete URL, replace the image inside the specific post or block with the correct library item. Save the draft or update safely, then inspect the rendered page.
When you replace an image, check the caption, link destination, crop, and alignment. WordPress Media & Text blocks need special attention: the image should sit beside related copy on wide screens and stack predictably on mobile. An image that is restored but pushes the text outside the viewport has not been fully fixed.
Avoid using CSS to hide broken icons without correcting their URLs. The underlying request still fails, and visitors may lose information. Likewise, changing the file extension in the text field is not a reliable conversion technique.
Check optimization and cache behavior
Image CDNs and optimization plugins may generate cached versions of media. If the original source works but a transformed URL fails, investigate the transformation service and its settings. Clear only the relevant supported cache after a repair and verify the actual served file. Repeatedly flushing every site cache without checking the request can make diagnosis harder.
Prefer appropriately sized images that retain acceptable detail. Compression reduces transferred bytes, but a file that becomes unreadably soft is not an improvement. Where supported, responsive formats such as WebP can be useful; always confirm that the chosen format is served correctly.
Use a consistent final verification
Once the image is repaired, reload the page, inspect the network response, and test mobile widths. Check that the displayed image is clear, the crop preserves important content, the page does not move unexpectedly as the image loads, and the surrounding text stays readable.
- Original and selected image URLs return successfully.
- Correct image is displayed at desktop and mobile widths.
- Intrinsic dimensions and aspect ratio are correct.
- Alt text is appropriate for the image’s purpose.
- No new horizontal overflow or excessive blank space appears.
- The image is not unexpectedly enlarged beyond useful resolution.
These same checks are useful when reviewing a local website design page or following our image optimization guide. Image repair and image optimization are related, but they solve different problems: first restore the correct image, then improve its delivery.
Prevent future image failures
Keep reliable backups of the uploads directory and database, preserve a URL inventory during migrations, and inspect representative pages after changing a theme or image optimization system. If a plugin replaces originals or regenerates sizes, confirm how to reverse the change before applying it site-wide.
Broken-image repair works best when each step is measurable. Find the failed request, confirm the intended attachment, update the smallest necessary part of the site, and verify that the browser displays the correct file. This method fixes the underlying problem without creating a second round of image or layout issues.