What to do if images are broken on your migrated website
What is happening is due to the manner in which WordPress optimizes image sizes. If you find that you have a page on your old site with an image that is broken in the migrated site, the good news is that it is straightforward to fix.
Why this happens
If a picture has larger dimensions than you need (for example, 1800 x 2600), in both the new and old WordPress sites the system creates smaller versions for use on the page— but the sizes of those smaller images are different in the new theme, and so the page is looking for a resized version that no longer exists.
On the old site, the “Medium” size was 167 x 250 pixels.
On the new site, a “Medium” size is 201 x 300 pixels.
Because of this, pages which used resized images will need to be checked, and when broken images are found, the process to fix them is as follows:
- Open the page for editing
- Click on one of the broken image icons in the page
- Click the “Edit” icon (a pencil)
- On the “Image Details” dialog box which appears, you’ll see a broken image icon to the right. There is a Size drop-down within “Display Settings”. Click that drop-down and select a different size… then click to re-select the size you had originally (Medium in this case).
- The image to the right should re-appear, indicating the system has found the correct image once again.
- Click “Update”
Note— this is a GREAT time to revisit the alternative text on images. While you are reviewing the Image Details, look at the text you see for “Alternative text” and ask yourself “will this be a good description of the image if it is read to someone using a screen reader?” If the text is the file name of the image, the answer is usually no.
Good alternative text should be descriptive of the image, for example “Photo of Susan J. Hunter” instead of “DCS005”.
As a bonus, good alternative text will help more people find your website, because Google’s Image Search feature will better characterize your images for people using search, allowing them to find your web pages.