Broken images: empty and placeholder src attributes

What this rule detects

A broken image is one whose src does not resolve to a file, so the browser shows its broken-image placeholder. The usual causes are a template variable that rendered empty, a path that moved, and a src="#" placeholder that was never filled in.

This rule catches the malformed sources rather than the missing files. It reads the markup and reports sources that are empty, a bare #, or an error data URI. An image URL that looks correct but returns 404 is not detected here, which is why the pass message says “no obviously broken images” rather than none.

What squirrel checks

The rule is site-wide. It walks the images of every crawled page, deduplicating by source, and emits a single check named broken-images:

• Skipped when there is no site data. Message: Site data not available.
• Fail when any source is empty, is exactly #, or starts with data:error. Message: 2 potentially broken image(s) found, each listed by source or as (empty), with the page it appeared on. Severity error, weight 6.
• Pass otherwise. Message: No obviously broken images detected.

No HTTP request is made for image URLs, so a well-formed URL that 404s passes this rule. images/image-file-size reports on the images the crawl did fetch.

Elements inside <noscript> are skipped: a browser with scripting enabled reads <noscript> content as plain text, so nothing in it loads or renders. See content inside noscript.

How to fix it

{photo?.url ? <img src={photo.url} alt={photo.alt} /> : null}

Guard the render on the source being present rather than emitting an <img> with an empty src. An empty src is worse than no element: some browsers re-request the current page for it.

Replace src="#" placeholders with the real path or remove the element.

Enable / disable

Disable this rule

[rules]
disable = ["images/broken-images"]

Disable all Images rules

[rules]
disable = ["images/*"]

Enable only this rule

[rules]
enable = ["images/broken-images"]

enable replaces the default ["*"], so this is the only rule selected. Leave disable out: a rule that matches any disable pattern is skipped even when enable names it. Only an enabled setting under a rule’s own [rule_options] table overrides both lists.

Related rules

• images/image-file-size: the images the crawl actually fetched and weighed.
• links/broken-links: the same idea for anchor targets.
• images/alt-text: the alt text a broken image falls back to showing.
• security/mixed-content: images blocked because they load over HTTP.

Images findings ship in every audit next to the SEO, performance and agent experience rules. See Core Web Vitals for how an agent works through a report.

References

• The img element, MDN

Check your site

Run squirrel audit https://example.com and open the Images section of the report. Every malformed image source is listed with the page it appeared on. Signed-out local audits need no account and cost nothing. Signed-in audits spend credits.