Broken images

A broken hyperlink fails only when someone follows it. A broken image fails on load, for every visitor, immediately.

A broken image also degrades differently depending on markup. With good alt text, a screen-reader user loses nothing and a sighted user sees a description; with `alt=""`, everyone gets a gap; with no alt attribute, many browsers show the file name.

That makes alt text a genuine mitigation here, which it is not for anything else. An image that fails to load and announces what it was is a considerably smaller failure.

And the causes differ. Links break because destinations move; images break because a file was not deployed, a path was rewritten, or a host stopped serving.

Migrations. Content moves between systems, the HTML comes across with absolute URLs pointing at the old host, and the images stay behind.

Deployments that exclude the media directory. Code ships, uploads do not, and everything added since the last full sync is missing.

Case sensitivity. `Photo.JPG` referenced as `photo.jpg` works on a developer's machine and 404s on a Linux server — a whole class of breakage that appears only in production.

Hot-linked third-party images, where someone else's server stopped serving, moved the file, or started blocking requests without a matching referrer.

Expired or rotated CDN URLs, particularly signed ones, which work until the signature's validity ends.

Editor-inserted images referencing a staging or preview host, which resolve while the editor is logged in and fail for everyone else.

404 or 410: the file is not there. Unambiguous, and the most common.

403: the server refused. On your own host this is usually a permissions problem on the file or directory; on a third-party host it is often hot-link protection.

5xx: the server failed while responding. Frequently transient, so re-test before editing anything.

200 with the wrong content type — an HTML error page returned with a 200 status where an image was expected. The request succeeded and the image still does not render, which is the case a status-only check reports as working.

A load error with no status at all, where the host does not resolve or the connection is refused. That points at DNS or at a service that no longer exists.

In the console: `[...document.images].filter(i => !i.complete || i.naturalWidth === 0)` returns the images that failed, after load. This is the most reliable single check because it reflects what the browser actually got.

The Network panel lists failed requests with their status, which gives the reason rather than only the fact.

The console itself logs a failed resource load for each one, which is the fastest signal while developing.

Across a site, this needs the list of pages first — the same crawl that finds broken links — because a broken image on a page nobody opened is still broken.

Check CSS backgrounds separately. They are not `<img>` elements, do not appear in `document.images`, and fail silently with no icon and no alt text.

Repoint or restore each file. A migration that left images behind usually needs a bulk search-and-replace in stored content, done on a copy first.

Normalise case on upload — lowercase file names as a rule — which removes the entire class of case-sensitivity failures.

Host your own images rather than hot-linking. Someone else's server is not a dependency you control.

Include the media directory in deployments, or serve it from storage that is not tied to a deploy at all.

Give every informative image real alt text, so the day one does break, the page still communicates. This is the only mitigation that works before you have noticed.

`images.broken` requests the images referenced by each crawled page and reports the ones that do not return a usable file, with the status and the page the reference appears on.

`images.inventory` gives the full per-page list, which is what turns a count into a set of edits.

`availability.broken_links` covers hyperlinks, and the two are reported separately because they are found, prioritised and fixed differently.

The check reports the response. An image that returns 200 with an HTML error body is reported by its content type rather than treated as working, which is the case a status-only test misses.