Practical guide · verified against the real thing
Why won't my website deploy? The diagnostic tree
In one line: Build red, build green but the site wrong, or nothing happening at all — the three failure families, in the order that finds the cause fastest.
The symptom: you push, and your site does not update. Or the deploy fails. Or it "succeeds" and serves something wrong. Before touching a single setting, sort the failure into one of three families — because each has a different first suspect, and testing in the wrong family wastes hours.
Family 1: the build fails
Likely causes, most common first: a dependency problem (missing package, version pinned differently locally than in CI — very common); an environment variable the build needs but the platform does not have (common); a build command that works interactively but not in a clean checkout (wrong working directory, global tools, case-sensitive filenames — common on Windows-authored projects); Node/Python version mismatch (occasional).
Diagnosis: read the build log bottom-up — the first error is usually above a wall of noise, but the last error is the fatal one; work between them. Then reproduce in a clean checkout: clone fresh, install, run the exact build command the platform runs. If it passes locally and fails remotely, it is an environment difference (versions, env vars, case). We debug our own builds exactly this way — this desk's builder once failed on a missing data key that only existed on our machines, and the clean-checkout rule found it in minutes.
Fix: pin your runtime version in the repo (a .node-version/runtime.txt-style file); commit every env var the build needs into the platform's settings (never the repo); make the build command runnable from a fresh clone by a stranger.
Family 2: the build passes but the site is wrong
Likely causes: the publish directory points at source instead of generated output (the classic); a redirect or header rule at the host shadowing your expectations; caching — the CDN or your browser serving the previous deploy; the deploy quietly serving the last good build after a later failure (static hosts do this by design — resilience that hides breakage).
Diagnosis: hard-refresh with cache disabled, then check the deploy log's timestamp against the change you expect. Curl the exact URL and look at the bytes, not the browser. If the bytes are old, you are either looking at the wrong publish directory or the deploy did not actually succeed — the build badge and the log, never the homepage, tell you the truth.
Family 3: nothing happens at all
Likely causes: the push never triggered a build (wrong branch watched — very common); the Git integration lost authorization; you are pushing to a fork/remote the platform is not watching.
Diagnosis: confirm the commit is on the branch the platform watches (git log origin/main is your friend), then trigger a manual deploy. A manual build that works means the automation is the problem; one that fails means it was Family 1 all along.
When this fix will not work
If a clean checkout, pinned versions, committed env vars and a watched branch all check out and the build still fails in a way you cannot reproduce locally, you may be hitting a platform-side limit (build minutes, memory on the build image). Keep the log excerpt — you will need it. And if the site serves but a path is wrong while the root works, that is routing, not deployment: check redirects before rebuilding anything. The deeper post-mortems from real failures live in what Render deployment failures taught us and the full Render static deploy walkthrough.
When to escalate
After a reproducible log, a clean-checkout test, and a status check on the platform's own status page — that is the evidence package support (or a forum) needs. Posts without the log get guesses; posts with it get answers.
Official documentation (checked 11 September 2026): Render deploys & troubleshooting (render.com/docs), GitHub Pages usage limits and troubleshooting (docs.github.com/pages), and your platform's build-log reference.
Next