# Startup assertions — the config errors that fail a deploy

URL: https://kywi-docs-production.up.railway.app/developing/startup-assertions--the-config-errors-that-fail-a-deploy
Type: docPage

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.

## the five shapes these failures take

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.

## Unset means true

`KYWI_REQUIRE_CONSENT` is read as false only when it is the literal string `false`. Setting `requireConsent: false` in a theme and leaving the variable unset is therefore a disagreement, and the error says `unset (which means true)`. Set both, or neither — [Consent policy: the startup throw and the env mirror](/operating/consent-policy-the-startup-throw-and-the-env-mirror/).

## 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](/operating/authsecret-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.

## url, email and list fields fail kywi migrate

All three are real `FieldType` values and render correctly, but the zod enum the migrator validates against lists only the other fifteen — so a type using one is rejected at `kywi migrate` time, usually on the deploy. [What a field type becomes in Postgres](/developing/what-a-field-type-becomes-in-postgres/) lists the types that survive a migration.

## 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](/operating/running-migrations-against-a-live-database/).
