# Recovering from a stuck host process

URL: https://kywi-docs-production.up.railway.app/operating/recovering-from-a-stuck-host-process
Type: docPage

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 first error, not the loudest one

Because the rejection is replayed rather than recomputed, a wedged process prints the same stack once per request and can bury the cause under thousands of identical copies. Scroll to the *earliest* occurrence in the boot; everything after it is an echo, and none of the later ones carries extra information.

## 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:

[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 warning, not a fault

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](/operating/post-migration-data-steps-and-why-they-can-silently-not-run/).

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

## Do not redeploy after changing service settings

`railway redeploy` re-uses the *previous* deployment's frozen settings, so it re-ran the pre-deploy hook that had just been cleared and hung again — the second lost deployment was the attempt to recover from the first. Trigger a fresh source deploy instead: the dashboard's Deploy button, a `serviceInstanceDeploy` call, or an empty commit.

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