A Renamed File Can Break Your Site For Nine Months

Published August 09, 2026

A stylesheet was renamed. One page was updated. Three others rendered unstyled for nine months and nothing reported it.

What happened

git mv currentIndexStyles.css index2styles.css

The page being worked on was updated in the same commit. Three others — all of them in sitemap.xml — kept the old name and have been served without any CSS since.

Why nothing caught it

• The pages return 200. The HTML is fine.
• The browser requests the stylesheet, gets a 404, and renders the document

  bare. A 404 on a subresource is not an error the page can observe.

• No build step, no bundler, no framework. Nothing between the author and the

  server ever knew the reference existed.

• The server log has the 404s, buried among every other 404.

The only signal was a person opening the page and saying it looked wrong.

Find them all in one pass

For every HTML file, resolve every local href and src and check the file is there. Three details decide whether the tool is useful:

1. Root-absolute paths resolve from the docroot, not from the page.

   /img/logo.png means the same file wherever it is referenced from. Getting this wrong reports a dozen files as missing that are sitting right there.

2. Skip external URLs. Someone else's uptime should not fail your check.
3. Distinguish public pages from orphans. Start from sitemap.xml, follow

   local links, and treat what you reach as the site. Breakage on those fails; breakage on a page nothing reaches is reported and does not. Derive it — a hardcoded "ignore this page" keeps hiding that page's breakage on the day someone finally links it from the nav.

Related things worth checking in the same sweep

• file:// URLs. One had been sitting on the homepage — a path that resolved on

  exactly one machine in the world.

• References from a template directory. A template that ships broken links

  produces pages that start life broken.

• Images referenced from a directory that has never existed in the repository.

  Not deleted — never there. Check the history before assuming a fix.

The rule worth keeping

A rename is the most ordinary edit there is, and in a site with no build step it is unverifiable by inspection. Make it verifiable by a command.

Written from Kevin's own working notes and formatted with the help of AIOS, then reviewed before publishing.

← Back to the Developer's Notebook