Fix: images — broken images, alt text and file size

Images are usually the heaviest part of a page and a common source of broken files and accessibility problems. This guide covers every image check in Site crawl and audit reports.

Find the affected images in the app

1. Site crawl › open the crawl › Issues › Broken images lists the broken image URLs (the first 20).
2. Site crawl › Resources: click Images to see every image with Size, HTTP status and Used on (how many pages use it).
3. Click Large files to see only images over 300 KB. Export gives the full list.
4. Site crawl › Issues › Images without alt text lists the pages that have at least one image without alt.
5. Audit report › Images (open the report from Audits) shows how many images lack alt text and how many are over 50 KB.

To list the images without alt on one page, open it and run this in the browser console (F12 › Console):

[...document.images].filter(i => !i.alt.trim()).map(i => i.currentSrc || i.src)

Broken images

How we detect it

After crawling, the app sends a HEAD request to each image it found (the first 150 resources of the crawl). Images that answer with a 4xx status are counted. It is an error.

Why it matters

Broken images look unprofessional, can break product pages and galleries, and waste crawl time.

Common causes

• If the image URL returns 404 → the file was deleted, renamed or moved (often after a domain or HTTPS move).
• If it returns 403 or 405 but opens fine in a browser → the server rejects HEAD requests, or hotlink protection blocks unknown referrers.
• If the image is on another domain → an external CDN or supplier feed removed it.

Fix: basic

1. Open the broken image URL in a new tab.
2. 404: upload the image again and replace it in the page (see Platform steps).
3. 403/405 but it loads in the browser: turn off hotlink protection or add the site’s own domains to its allowed list (see Platform steps).
4. External image: download it, upload it to the client’s own site and update the page.
5. Remove the image if it is no longer needed.

Fix: expert

Check how the server answers:

curl -I https://example.com/wp-content/uploads/photo.jpg

You want 200. If HEAD returns 405 in nginx, look for a rule limiting methods and allow HEAD:

# Allow GET and HEAD for static files
location ~* \.(jpe?g|png|webp|avif|gif|svg)$ {
    limit_except GET HEAD { deny all; }
}

WordPress: fix old upload paths everywhere after a domain move (backup first; the first line is a dry run):

wp search-replace 'http://old-domain.com/wp-content/uploads' 'https://example.com/wp-content/uploads' --all-tables --dry-run
wp search-replace 'http://old-domain.com/wp-content/uploads' 'https://example.com/wp-content/uploads' --all-tables

Platform steps

WordPress

1. In WordPress admin, Media › Add New to upload the image again.
2. Edit the page, select the image block › Replace › choose the new file › Update.

Shopify

1. Re-upload in Shopify admin › Content › Files, copy the new URL.
2. Update the section (Online Store › Themes › Customize) or the product description, Save.

Webflow / Wix / Squarespace

1. Replace the image in the editor and publish.

cPanel

1. In your host’s cPanel › Security › Hotlink Protection: add the site’s own domains to URLs to allow access, or click Disable.

Cloudflare

1. Cloudflare dashboard › your site › Scrape Shield › Hotlink Protection: turn it off, or allow the crawler (see Fix: Cloudflare blocks the crawl).

Verify the fix

1. Reload the page in a private window and check the images show.
2. curl -I on the image returns 200.
3. Site crawl › open the crawl › Crawl again, then Compare: Broken images should be under Fixed issues.

Automation

Assisted: detection is automatic; re-uploading and replacing images needs WordPress admin, the Shopify Admin API (Files) or CMS access; server rules need SSH.

Images without alt text

How we detect it

The crawler checks every <img> that has a src or data-src. If any image on a page has a missing or empty alt, the page is counted. It is a warning. Empty alt="" counts as missing.

Why it matters

Alt text is how Google Images understands a picture and how screen readers describe it. Missing alt text is an accessibility failure (WCAG) and a lost image-search opportunity.

Common causes

• If images were inserted before alt text was written → the editor saved them without alt.
• If you updated alt in the media library but the page still lacks it → images already placed keep their old alt.
• If the images are in sliders, galleries or builder backgrounds → those often have no alt field.
• If they are decorative → alt="" is correct and can be left.

Fix: basic

Write alt text that describes the image in about 5 to 15 words. Use the keyword only where it fits naturally.

1. Open each flagged page and list its images without alt (console snippet above).
2. Add alt text to each meaningful image (see Platform steps).
3. For decorative images, leave alt="" and accept the notice.

Fix: expert

<img src="/images/leeds-plumbing-team.webp" alt="The Smith Plumbing team outside our Leeds office" width="800" height="533">

Platform steps

WordPress

1. Media › Library › click the image › fill in Alternative Text (saves automatically). This sets the default for new inserts.
2. For images already in posts: select the image block › Block settings › Alternative text › Update.
3. Elementor: the Image widget takes the alt from the media library; update it there and re-select the image.
4. WooCommerce product images also take their alt from Media › Library.

Shopify

1. In Shopify admin › Products, open the product › click the image › Add alt text › Save.
2. Theme section images: set alt in Content › Files or the section’s image settings.

Webflow

1. Select the image › Settings › Alt text › Custom description (or Decorative). For CMS images, fill the alt field on the item. Publish.

Wix

1. Click the image › Settings › What’s in the image? Tell Google › type the alt text › Publish.

Squarespace

1. Edit the image block › Content › Image alt text › Save.

Verify the fix

1. Run the console snippet: it should return an empty list (or only decorative images).
2. In Site crawl, open the crawl › Crawl again, then Compare: Images without alt text should move to Fixed issues.

Automation

Automatable: alt text can be drafted from the image and page context and written via WordPress admin (media library API), the Shopify Admin API (product image alt) or the Webflow CMS API; review before publishing.

Image alt text

How we detect it

The audit counts images on the page with and without alt text, for example “3 of 12 images have no alt text”. Any missing alt fails the check. In ”+” audits, Lighthouse may also show Image elements do not have [alt] attributes.

Why it matters

Alt text helps blind visitors and lets images rank in Google Images.

Common causes

• Same as Images without alt text above.

Fix: basic

1. Follow Fix: basic under Images without alt text for the audited page.

Fix: expert

Use the HTML example under Images without alt text.

Platform steps

All platforms

1. Use the platform steps under Images without alt text.

Verify the fix

1. Open the report in Audits and click Run again. Image alt text should say “Every image has alt text.”

Automation

Automatable: same access as Images without alt text.

Image file size

How we detect it

The audit groups the page’s images by size and fails if any image is larger than 50 KB (“N images are larger than 50 KB”). The crawl’s Resources › Large files chip shows images over 300 KB across the site.

Why it matters

Large images are the most common cause of a slow page, especially on phones. The main hero image is often the Largest Contentful Paint (LCP) element, a Core Web Vital (see Fix: Core Web Vitals › LCP).

Common causes

• If images are 2000–6000 px wide but shown at 800 px → uploaded straight from a camera or stock site.
• If they are PNG photos → wrong format; PNG is lossless and heavy for photos.
• If the site has an optimizer but images are still big → the bulk optimization was never run on old images.

Fix: basic

Target: content images under about 100 KB, hero images under about 150 to 200 KB, thumbnails under 30 KB.

1. Resize to the size shown: export at about 2× the display width at most.
2. Convert to WebP or AVIF and compress (quality 75 to 82 is usually invisible).
3. Lazy-load images below the fold, but never the main hero image.
4. Set width and height to prevent layout shift.
5. Replace the images on the page (or run your optimizer’s bulk mode).

Fix: expert

Convert by command line (needs cwebp from libwebp):

# WebP at quality 80, max 1600 px wide
cwebp -q 80 -resize 1600 0 hero.jpg -o hero.webp

Serve modern formats with a fallback:

<picture>
  <source srcset="/img/hero.avif" type="image/avif">
  <source srcset="/img/hero.webp" type="image/webp">
  <img src="/img/hero.jpg" alt="Slate roof repair in Austin" width="1600" height="900" fetchpriority="high">
</picture>

Shopify responsive image (remove loading: 'lazy' for the first visible image):

{{ product.featured_image | image_url: width: 1200 | image_tag: loading: 'lazy', widths: '400, 800, 1200', sizes: '(min-width: 990px) 50vw, 100vw' }}

Platform steps

WordPress

1. Install one image optimizer (not several): ShortPixel, Imagify, EWWW Image Optimizer, or LiteSpeed Cache’s image optimization.
2. LiteSpeed Cache: LiteSpeed Cache › Image Optimization › Send Optimization Request, then turn on Image WebP Replacement under Image Optimization Settings.
3. Run the bulk optimize on the existing library.
4. WordPress adds loading="lazy" and srcset automatically for images inserted through the editor.

Shopify

1. Upload product photos at 2048 px wide at most. Shopify’s CDN serves WebP/AVIF and resized versions when the theme uses image_url with a width (snippet above).

Webflow

1. Assets panel › select images › Compress / convert to WebP or AVIF › Publish.

Wix / Squarespace

1. Both compress and convert automatically. Upload JPGs under about 2,500 px wide and avoid huge PNG photos.

Any site

1. Compress by hand with a free tool such as Squoosh, then replace the file.

Verify the fix

1. curl -I on the image shows a smaller content-length.
2. Click Run again on the audit in Audits and check Image file size; after a crawl in Site crawl, Resources › Large files should list fewer images.

Automation

Automatable: compression and WebP conversion can run automatically via WordPress admin (optimizer plugin) or server SSH; Shopify, Wix and Squarespace need only re-uploads through their admin or API.

Image file name lines

How we detect it

The classic audit scanner checks image file names and writes lines such as Image name have underscore, Image name is too long, Image name is readable, Image name have keyword and Image alt have keyword.

Why it matters

Descriptive file names are a small signal for image search. Search engines read hyphens as word separators, not underscores.

Common causes

• If names look like IMG_0042.jpg or DSC00123.jpg → uploaded straight from a camera.
• If names use _ → exported by design tools with underscores.

Fix: basic

1. Underscore: rename roof_repair_austin.jpg to roof-repair-austin.jpg.
2. Too long: keep names to about 5 words.
3. Not readable: replace camera names with descriptive words.
4. Keyword: where it fits, include the keyword in the main image’s name.
5. Rename before upload when you can; renaming a live image changes its URL.

Fix: expert

Bulk-rename local files before upload:

for f in *_*.jpg; do mv "$f" "${f//_/-}"; done

Platform steps

WordPress

1. Renaming after upload needs a plugin such as Phoenix Media Rename, which also updates the links. Otherwise upload a renamed copy and replace the image in the page.

Shopify / Webflow / Wix / Squarespace

1. Upload a renamed copy and replace the image in the editor.

Verify the fix

1. Click Run again on the audit in Audits and check the image name lines in the Images section.

Automation

Assisted: renaming needs WordPress admin via plugin or re-uploads through the CMS; low priority compared with alt text and size.

Common questions

Related articles

• Fix: Broken internal links (4xx) and broken resources
• Fix: Core Web Vitals — LCP, INP and CLS
• Fix: page speed — slow pages, TTFB, page size, requests, compression and caching
• Crawl a whole website

Still need help?

Ask in the chat inside the app, or send us a message on the contact page. You can also browse all help topics.