Build Failures

When the static builder fails, the site does not go down: your previous build keeps serving until you fix the problem and rebuild. This page explains where build failures are reported, what the different outcomes mean, and what to try.

Where to look

Two places tell you how the last build went:

Dashboard: build status panel. It shows the current state plainly: build in progress, the last built time, Build Failed (with “Last build exited with an error: site may be out of sync. Check build history below.”), or Promotion blocked when a build lost too many pages (the exact reason from the build itself is shown).
Build history. The last 100 builds are kept with their full output: each row shows OK, Error, or Blocked, the timestamp, the number of files written (or the failure message), and the complete build log in an expandable section.
A /health-style status URL also answers with the last build time and whether a build is currently running, for monitors.

The three outcomes

Error: the builder hit render errors (for example a broken template) and refused to promote. The staging output is discarded and the previous live output stays in place. The failure message lists the failing templates, like “page.tt for ‘about’” (first few, then the count of the rest).
Blocked: the build finished, but the builder compared it against the last good build and saw too large a drop (more than 80% of pages lost) or a spike in broken links or accessibility issues, which usually means the build was broken even though it “succeeded”. The previous build continues serving: stale content, never broken content.
OK: everything promoted; the row shows how many files were written plus the full log.

First things to try

Full rebuild. A clean full rebuild re-renders every page from scratch. If an incremental build seems to have missed your changes, this clears the build cache and rebuilds from scratch; the dashboard’s “Full rebuild” button does this (with a confirmation; it is slower than the incremental default). Emergency environment variable CHINASKI_FORCE_FULL=1 does the same from an ops script.
Promote anyway. If a build was blocked but you are confident it is correct, “Promote anyway” on the dashboard pushes it out bypassing the guard for that one build. This is a one-shot escape hatch: it doesn’t reset measurements the guard compares against, and is meant to stay an unusual path.
Check the health endpoint. It’s the fastest way to see if a pre-existing environment problem caused the failure: output directory writable, free disk space, builder file present, template engine compiles, and so on.

What usually causes a failed build

The most common sources of failure messages are:

Template render errors: a page or block failing to render. The message names the first three failing templates.
The startup environment: running the builder as root (it refuses), missing database file, or missing build script.
Resource ceilings being hit. A build aborts when it tries to write more than the 2 GiB write budget; each build also has a 30-minute wall-clock limit. After that the build is killed and the previous output stays serving.
Manifest signing. Builds sign their file manifest, and a green build with no valid signed manifest is treated as a failure; promotion aborts. Test environments can opt out with an environment flag.

Where the log lives once fixed

After a failure, the build history’s expandable rows are your best tool: the full output of the failed build is there for copy-paste into a support ticket, plus the counts of the failing templates to narrow the problem.

Reason counts and their effects

A build reaches the promotion step only when there are zero render errors. Any render error (even one) blocks promotion outright.
Fatal (start-of-build) errors keep the live site running because the previous build isn’t replaced after failure.