Every photo on my site was broken, and the reason taught me how the web works

In late August I gave this site a small upgrade: each project card on the home page got a photo, and I built myself a little admin editor so I could upload and swap those photos without touching any files. I uploaded the first photo, the editor said it saved, I refreshed the page — and got a broken image icon.

Then I checked the other cards. Every photo on the site was broken. Not one of them loaded.

The confusing part: nothing was missing

If you can't code, this is the kind of bug that makes you want to give up, because every individual piece looks fine. The upload succeeded. The file really existed on the server — I could see it. The page really was asking for the image — I could see the request in the browser's developer tools, returning 404 Not Found for a file I knew existed.

The browser and the server were both telling the truth. They were just talking about different places.

What was actually happening

Hatch & Build isn't one server pretending to be one website — it's two. The page you're reading lives at hatchandbuild.com, which is a plain static site. But the drawing wall and the project data live on a second server at drawing.hatchandbuild.com, and that's also where my new upload feature saved the photos.

When a photo was uploaded, the server recorded its location as a relative path — something like /hub-images/project-1.jpg. No domain in front, just the path. And here's the rule I had never learned: a path without a domain is not an address, it's a fragment of one. The browser completes it using whatever domain the current page is on.

So the photo was sitting at drawing.hatchandbuild.com/hub-images/project-1.jpg, but the page displaying it was on hatchandbuild.com — so the browser politely asked hatchandbuild.com/hub-images/project-1.jpg, a place where no photo has ever existed. Hence: 404, for a file that absolutely existed. Both servers were right. I had simply never told the browser which one to ask.

The fix was three lines

Once I understood the problem, the fix was almost insultingly small: before putting an image path into the page, check whether it starts with /hub-images/, and if so, glue the API server's full address onto the front. Paths that are already complete addresses get left alone. Three lines of code, one afternoon of confusion.

I also left a comment in the code explaining why those three lines exist — because the version of me who finds this code in six months will not remember, and will be very tempted to "clean it up."

What I actually learned

• A URL has parts, and the parts matter. Domain, path, and the rules for combining them. I'd been using URLs for twenty years without knowing the browser fills in missing pieces from the current page.
• "It works" and "it works from where the user is standing" are different claims. The upload worked perfectly — from the server's point of view. Nobody was checking the browser's point of view, which is the only one that matters.
• The developer tools' Network tab is not just for developers. Seeing the actual request the browser made — the full URL, the 404 — is what turned a mystery into a fact. If you're building without a coding background, learning to open that tab is worth more than most tutorials.

This is what building without a background actually looks like. Not smooth demos — a broken image icon, an evening of asking "but the file is right there," and then one small rule about how the web works that I'll never forget again.

More of these as they happen — and they will happen. Follow along on Instagram or check the build log.