Skip to content

Recovering from a stuck host process

A failed boot is memoised for the life of the Node process, so every later request replays the same error and recovery is a restart, not a retry.

The runtime initialises once and caches the promise, not the result. Every request awaits that same promise — so if initialisation rejected, every request from then on replays the identical rejection, in a process that is otherwise alive and answering. Nothing clears it. Restart the process; a retry cannot succeed.

Read the boot as a checklist

Initialisation does six things in a fixed order, and the last log line before silence tells you which one threw: resolve the database URL, create the pool, resolve the auth secret, create the storage provider, reconcile the configured sites into kywi_sites, then construct the API handler and the scope. Five of the six take the process down on failure.

Site reconciliation is the exception, and it is deliberate — a read-only database role or a table migrations have not created yet is not a reason to refuse to serve the sites that do have rows. It logs one line and carries on:

a warning, not a faulttext
[kywi] could not reconcile config sites (<message>). Continuing with the sites
already in the database — a site declared in kywi.config.ts but missing a
kywi_sites row will not resolve until this succeeds. Run `kywi migrate` to complete it.

A site declared in the config that 404s on its own home page after a first deploy is usually this line, several thousand requests up the log. Two other [kywi] lines on a healthy boot report sites created or updated, and site rows matching no config site — both are inventory, not errors, and Kywi never deletes a site row. See Post-migration data steps.

The deploy that hangs is usually not the app

A migration wired as a pre-deploy hook can prompt, and a prompt written to a non-TTY waits forever — the deployment never finishes and it blocks every later one behind it. Recovery is to cancel that deployment through the platform's API (the Railway CLI at 5.26 has no cancel; the GraphQL deploymentCancel mutation does it, with the token from ~/.railway/config.json), then clear the hook so it cannot recur. This deployment lost two deployments to it. Migrations belong on an operator machine, before the push — Running migrations against a live database.

The crash report that is not a crash

If every rollover files a crash while the new container is healthy, read the retired deployment's log. Ending in ELIFECYCLE Command failed. after Stopping Container means the package manager, not the app, reported the failure: pnpm treats a child ended by SIGTERM as a failed script and exits non-zero. Set an explicit start command that runs the Next binary directly (Deploying a host app), after which a retired log ends at Stopping Container and nothing follows it.

Two things that will not wedge a process

The scheduler and the webhook retry worker, if your host app starts them. Both unref() their interval so neither holds the event loop open on its own, both skip a tick rather than overlapping when a sweep runs long, and both route every error to a handler that logs — a failed sweep never reaches the process. And transient 404s in the seconds after a deploy switch are edge routing catching up: re-probe before investigating. There is no health endpoint and no diagnostic command in the CLI's six, so the log is the instrument.