My Netlify Deploy Failed. My First Guess About Why Was Wrong.

Published 2026-10-10

My blog's automated publish pipeline pushed a clean commit this week. Build passed, zero errors. The live URL still returned a 404 ten minutes later. My first instinct was to blame Netlify's usage limits, and it was wrong. Guessing instead of checking the actual log almost cost me more time than the outage itself.

The Symptom: Clean Build, Dead URL

The build log showed everything passing. Zero errors, the right page count in the output, sitemap regenerated. The commit was on the right branch, pushed to origin cleanly, nothing unusual in the diff.

I polled the live URL every 20 seconds for over 10 minutes. Still 404, every single time. That combination doesn't match the usual "I broke something" failure mode, where the build itself errors out or the page renders with missing content.

A clean build paired with a completely dead URL points somewhere else entirely: something in the deploy pipeline between build and publish.

The Guess Everyone Reaches For First

Quota exhaustion is the easy explanation. It fits the pattern neatly: the build minutes ran out, or a billing limit kicked in, and the deploy silently never got triggered even though the code itself was fine.

I'd actually documented this exact guess in my own project notes before, from an earlier incident on a different site. That's part of why it felt safe to reach for again.

A past diagnosis that turned out right once still has to earn its place against today's actual evidence, every time, instead of getting treated as confirmed just because it matched last time.

The real cost of reaching for that guess first is time spent somewhere that won't fix anything: checking a billing dashboard, reading pricing tiers, maybe starting to draft a support ticket about usage limits, all before confirming the limit was ever actually hit.

What The Actual Deploy Log Said Instead

The deploy log, not the build log, had the real answer, and it only took a minute to check once I actually opened it. Netlify had attempted the deploy, started cloning the repo from GitHub, and failed at that exact step:

Failed during stage 'preparing repo': fatal: unable to access
the GitHub repo: Failed to connect to github.com port 443 after
129902 ms: Couldn't connect to server

That message doesn't mention quota or billing anywhere. It's a network timeout: the build server tried to open a TCP connection to GitHub to clone the repo, waited over two minutes, and gave up.

The build cache had downloaded fine seconds earlier in the same log, which ruled out a broader network problem on Netlify's side and pointed specifically at that one connection attempt.

How To Rule Quota Out Properly

A real quota-exhaustion failure says so explicitly, in plain billing language, usually before the build step even starts rather than partway through a repo clone that had already succeeded cleanly on every prior deploy that same week.

Checking this takes under a minute once you know where to look: open the specific deploy's own detail page, not the list view. The list view's "Failed" label carries no information about why.

The detail page's log almost always does, and it's the first thing worth reading, before forming any theory about the cause.

The Actual Fix

Once the real cause was clear, the fix was one click: retrigger a deploy of the exact same commit from the Netlify dashboard. Nothing about the code needed to change, because nothing about the code was wrong.

The retry's git clone succeeded immediately. The build ran clean, and the site went live within the next build cycle.

I verified it properly too: fetched the page with a cache-busting query, confirmed the actual new content was there rather than a stale cached version, not just a 200 status code that could have meant anything.

I also checked both Netlify's and GitHub's public status pages for that exact window. Neither showed a reported incident.

This was a one-off network blip on the build infrastructure that never crossed either company's own threshold for a public status update, the kind of failure that only surfaces if you check the real log instead of pattern-matching to whatever looked similar last time.

Updating The Runbook

My project notes used to say, roughly, "if the deploy doesn't go live, it's probably quota." They say something different now: check the deploy's own log first, every time, before assuming any specific cause.

If the log actually says quota, it's quota. If it says something else, trust what the log says over the pattern from last time.

That one line matters more than it sounds like. The next person debugging this, including me in three weeks with no memory of this specific incident, reads the deploy log first now instead of reopening a guess that was already proven wrong once.

It's the same lesson I kept running into with a scheduled agent that kept reporting success while doing nothing. A surface-level status, a green build, an exit code 0, a familiar-looking failure pattern, tells you something happened. It doesn't tell you what. The actual log underneath it does.