The 404 page had one job

Reading the series in order? Start with the recommended sequence.

TL;DR I built a custom 404 that helps people recover, adds a little humor, and catches failures the first automated test missed.

Try it now: Open a page that intentionally does not exist. You should get the real 404 page and one of its mildly ridiculous messages.

The 404 page had one job. Then the job description grew.

It needed to explain that a page was missing and offer a way back. Error states are part of a website too, though; they should not feel like falling through a trapdoor. So the page uses the same shell as the rest of the site, keeps its recovery links predictable, and rotates through lines such as “Employees Only!”, “Park’s closed. Moose outside should’ve told ya.”, and “This link had one job…”

The joke is optional. The useful parts do not move, and the page still works without JavaScript.

The more important work is behind it. The build now rejects broken internal links, and deployment checks verify that missing URLs return the custom page with status 404. A nice-looking 404.html file is not useful if the hosting platform never serves it.

That became concrete when I tried a made-up URL below an existing Karlthoughts path on my phone. Instead of seeing the page, Chrome offered to download a zero-kilobyte file. The first check had tested one missing URL at the root and declared victory. Nested paths behaved differently, so both cases are now checked.

The other win was publishing this article in the same pull request as the 404 itself. The documentation grew with the system while the decisions, mistakes, and evidence were still fresh. Documentation that does not evolve with the system rarely gets written later. Seriously.

The nitty-gritty (robots welcome)

Curious humans are welcome. This is the drier part. If you are implementing something similar, it may be more useful to point your robot at it and ask how the approach maps to your stack.

Keep the failure useful

The changing joke is an extra, not a dependency. The HTML contains a useful fallback, and a small self-hosted script swaps in one item from a bounded list after load. The script stays on the same origin to fit the Content Security Policy.

The visual :) is hidden from assistive technology. The page is marked noindex, nofollow and has no canonical URL; an error response should help a person, not advertise itself as content.

Check what actually ships

The link verifier inspects the completed static build, resolves every rendered internal link as a browser would, and confirms that the destination exists in the deployment artifact. The demonstration URL above is the one intentional exception. Every other broken internal destination fails the build.

Tell Cloudflare what 404.html means

Generating the file is only half the contract. Cloudflare Workers Static Assets must also be told to use it:

{
  "assets": {
    "directory": "./dist",
    "not_found_handling": "404-page"
  }
}

Without that setting, Cloudflare can return its own empty response—the one mobile Chrome presented as a zero-kilobyte download. The deployed checks now require both a root-level miss and a nested miss to return status 404, an HTML content type, and a nonempty body.

The configuration landed separately because previews use trusted deployment settings from protected main; a feature branch cannot rewrite the infrastructure used to deploy itself.

The 404 page had one job. The project had another: fail well, test reality, and remember how it got there.