Skip to main content

Application will not start

Symptoms​

The API process exits during bootstrap, or Compose shows the API unhealthy.

Likely causes​

  • .env missing a required group. S3 settings, AI base URL, key, and model names, JWT secrets, database URL, Redis URL, and CREDENTIAL_VAULT_KEY_V1 are required. See Environment.
  • APP_ENV=production without SENTRY_DSN, or JWT secrets that match or are shorter than 32 characters.
  • A partial integration group. Setting RAZORPAY_KEY_ID or SMTP_HOST or an Amazon client id without the rest of that group fails validation.
  • Migrations have not been applied. Compose comments and the bootstrap runbook say the health check fails until yarn migrate:deploy has run.
  • Node version. engines says >=24. The README says 20+. Unknown which one CI uses. The process may refuse to start under an engine check if Yarn enforces it.

How to investigate​

  • Read the Pino log from the process that exited. main.ts bootstrap catch logs and calls process.exit(1).
  • Compare .env to .env.example and to environment.validation.ts.
  • Confirm Postgres and Redis from Compose are up.

Useful commands​

cd pnxt-api-nestjs
docker compose up -d
docker compose run --rm api yarn migrate:deploy
yarn start:api

Relevant logs​

Bootstrap exception on stdout/stderr. Validation errors name the missing variable. Do not paste secret values into tickets.

Resolution​

Set the missing configuration and migrate. Embedding and AI gateway downtime is not supposed to block boot. The embedding service catches those failures. A missing AI setting still fails validation. Those are different.

Unknown​

Exact production Node version. Whether a particular host runs engine checks.