Startup assertions — the config errors that fail a deploy
Four things can fail a Kywi boot, plus two more at config evaluation: a stale layer registry, a split consent policy, a missing auth secret, no database URL.
Each check below describes a misconfiguration whose runtime symptom would be misleading, so it is raised where the cause is still visible — at build, at boot, or when the config is evaluated.
The layer registry is checked at module load
All three constructors run assertLayerContracts first, and the generated route files construct at import — so a kywi.layers.ts that no longer matches kywi.config.ts fails next build or server start, not the first request to hit the wrong site. Three things are checked, in both directions where the check is about a name existing on the other side: every configured site has a registry entry and an entry for the theme it names, and a registry entry naming a theme your config no longer defines is caught the same way; all themes registered under one site declare the same region names; and every module key in a layer is a built-in or something config.modules declares.
kywi.layers.ts is stale: configured site "docs" is missing from the generated registry.
kywi.layers.ts is stale: site "docs" references theme "docs" but the registry does not import it.
kywi.layers.ts is stale: site "docs" imports theme "print" but kywi.config.ts does not define it.
Theme contract mismatch for site "docs": theme "print" regions [footer, main] do not match theme "docs" regions [footer, header, main].
Unknown layered module "splitFeature" in sites.docs.themes.docs. Define it in kywi.config.ts modules or use a built-in module name.Add a site or rename a theme and the registry is stale until create-kywi-app upgrade rebuilds it from your config. One caveat: the assertion returns immediately when no registry is passed, so a constructor called without layers is unchecked rather than checked-and-empty.
Consent has to be one answer per deployment
Edge middleware cannot read kywi.config.ts, so theme.personalization.requireConsent is mirrored into the environment as KYWI_REQUIRE_CONSENT — one process-wide variable that cannot carry a value per site. Two assertions protect that: one fails when configured sites disagree with each other, the other when the env var disagrees with the config. Both throw while the API handler is built, so the deploy stops rather than running with the middleware writing visitor cookies the API declines to read.
The database URL and the auth secret
With neither config.db.url nor DATABASE_URL set, the runtime throws a message carrying the createdb line instead of surfacing a connection error later. The auth secret is asymmetric by design: in production a missing or known dev-fallback secret is a hard error, because tokens signed with a public default are forgeable; in development it is allowed and warned about loudly. The generated kywi.config.ts calls assertProductionAuthSecret(process.env.AUTH_SECRET) at import, so kywi migrate and kywi seed refuse for the same reason. See AUTH_SECRET and production fail-fast.
Two helpers throw before any of that
defineSite rejects a site with no id, name or domain; defineTheme rejects a theme with no name or an empty regions array. Both fire at config evaluation — anywhere the config is imported, including kywi migrate and kywi seed.
The schema validation the app never runs
Kywi has a zod schema for the whole config, and the Next app does not use it. validateConfig is reached only through parseKywiConfig, whose only caller is kywi migrate:generate; the app imports its config as a module and trusts TypeScript. So a config the app has run happily for weeks can still fail the CLI.
What is deliberately not an assertion
Site reconciliation. If writing kywi_sites fails — a read-only role, a table migrations have not created yet — the runtime logs one line naming the cause and carries on with whatever the table already holds, because the sites that do have rows still serve. kywi migrate runs the same reconcile, and a site declared in the config but missing its row will not resolve until one of them succeeds — so that line is worth grepping for after a first deploy. See Running migrations against a live database.