Troubleshoot a project
Match a symptom to its cause and fix: setup gaps, session secret, generated types, migrations, development sign-in, the agent, scheduled jobs and repository access.
Most problems in a new project come from missing configuration, which the app reports as not configured. Start with the three checks below, which locate most causes. Then find your symptom in the sections that follow.
Before you begin
- A terminal in the project directory, and access to the environment the app runs in (
.envlocally, the platform's variables in production). - An administrator account, for the checks that use
/setup. See Run the admin console. - The exact error text or the page you ended on. Several fixes below depend on it.
Find the cause
-
Open
/setupas an administrator. It reads live configuration on every load and lists each item as Ready or Not ready with the reason. The first line states the platform, database and whether the build includes the agent service. -
Read the server output in the terminal running
pnpm dev, or in your platform's logs. Startup errors and the development sign-in warning are printed there. -
Run the gate. It runs every validator expected to pass and compares the result with
scripts/validate/known-failures.json:pnpm validate:gate
A feature says it is not configured
Providers are never mocked. Without credentials a feature reports that it is not configured.
| What you see | Cause | Fix |
|---|---|---|
/setup shows Email delivery as Not ready; verification and reset mail never arrive | No active email provider | Settings → Email Config (/admin/config/email). See Send transactional email |
A plan button on /pricing ends on /system/payment-failed with reason=checkout_not_configured | No payment provider is configured | /admin/config/payment. See Connect a payment provider |
/pricing says plans have not been published | No plan with status active for that locale | /admin/plans. See Pricing plans |
Uploads fail; /setup shows Object storage as Not ready | No storage driver | /admin/config/storage. See Store files |
AI tasks cannot start; /setup shows AI channels as Not ready | No active channel, or channels exist but no scene routes to them | /admin/config/ai. See AI providers and Scenes |
Saving a settings page confirms that the values were stored. It does not confirm that the provider accepts them. Use the page's own test action, then go back to /setup.
/setup will not open or shows gaps
- It redirects to
/system/session-expired: you are not signed in. Sign in at/auth/sign-in. - It opens but the checklist does not load: reading the checklist needs
config.read. Sign in with the account created bypnpm db:bootstrap-super-admin, or grant the permission. See Manage users, roles and permissions. - Required items are Not ready: the four required items are Session secret, Sign-in method, Email delivery and Scheduled jobs. Every item except the session secret and the scheduled jobs has a Configure button that opens the page that fixes it.
- An item shows an error message instead of a reason: that subsystem could not be read, usually because its table is missing. See Migrations were not applied.
The session secret is missing or rejected
BETTER_AUTH_SECRET signs sessions. What happens without it depends on APP_ENV:
APP_ENV | Behaviour |
|---|---|
development (or unset) | The app starts on the secret built into the template. /setup shows Session secret as Not ready: "BETTER_AUTH_SECRET is unset or still the template default." |
| Anything else | The app refuses to start: Refusing to start with the built-in session secret while APP_ENV is "production". |
Generate a value and set it in .env or your platform's secret store, then restart:
node -e "console.log(crypto.randomUUID()+crypto.randomUUID())"Use a different secret for production: kernlift deploy-target generates one into .env.production.
pnpm typecheck fails on Worker types
Errors about CloudflareEnv or other Workers types mean worker-configuration.d.ts does not exist. The file is generated and is not committed:
pnpm cf-typegenRun it after cloning and after changing bindings in wrangler.jsonc. A project deployed to Fly.io, Railway or Docker has no wrangler.jsonc. The same command then generates the types from a reference configuration, because the source still references them.
If the errors mention a route you just added, src/routeTree.gen.ts is stale. Start pnpm dev once, or run pnpm build, to regenerate it.
Migrations were not applied
Pages that load data fail with database errors that name a missing table or column, right after cloning, upgrading or installing a module.
| Database | Command |
|---|---|
SQLite or Postgres from DATABASE_URL | pnpm db:migrate |
| Cloudflare D1, local | pnpm db:migrate:d1:local |
| Cloudflare D1, deployed | pnpm db:migrate:d1:remote |
pnpm db:migrate reads DATABASE_DIALECT and DATABASE_URL from the environment, so check that they point at the database the app uses. When it fails it prints the dialect, the database, and the counts of migration files and applied records. If it adds "The schema exists but no migration has been recorded", the database was not created by migrations. Start from an empty database. Do not migrate over the existing one.
After merging an upstream update, run pnpm install && pnpm db:migrate, then pnpm db:bootstrap-super-admin so the Super Admin role receives any permissions the update added.
Development sign-in bypass does not work
Unauthenticated requests are treated as a chosen user only when both of these are true:
APP_ENV=development.AUTH_DEV_IMPERSONATE_USER_IDis set to a non-empty user id.
When it is active the server logs once: [auth] AUTH_DEV_IMPERSONATE_USER_ID is set. Unauthenticated requests are being treated as "<id>". If you do not see that line, one of the two conditions is false or the server was not restarted after editing .env. The value must be the id of a user that exists, and that user needs admin.access to open /admin.
Outside development the variable is ignored. There is no other identity fallback. An unauthenticated caller is rejected and is never mapped to a default user. See Authentication and authorization model.
The agent says it is not deployed
The agent is optional. Without it, /app/ai and /app/chat still work, agent entries are hidden from the sidebar, the agent pages say "The agent service is not deployed", and /api/agent/* returns 503 with agent_unavailable. The page states which of four reasons applies:
| Reason | Fix |
|---|---|
| The agent plugin is switched off | Enable it at /admin/plugins |
| The database has no transactions | Agent runs cannot use D1. Deploy on Postgres or SQLite |
| No agent service is configured | Set AGENT_SERVICE_URL (or the Cloudflare container binding) and deploy the agent service |
AGENT_INTERNAL_SIGNING_SECRET is not set | Set the same value for the web app and the agent service |
Locally, pnpm dev starts the web app alone. pnpm dev:agent starts it with the agent service. See Agent starter.
/setup warns about scheduled jobs
Background work (credit expiry, billing fulfilment retries, AI task polling) runs once a minute and records each round. Scheduled jobs becomes Not ready when no round has been recorded, when the last one is more than five minutes old, or when the last round had a failing job. The message names the failed job.
| Platform | How rounds start | Check |
|---|---|---|
| Cloudflare | The Worker's Cron Trigger | wrangler.jsonc keeps "triggers": { "crons": ["* * * * *"] } and the deployed Worker lists the trigger |
| Fly.io | Inside the web process | min_machines_running = 1 in fly.toml; a stopped machine runs no jobs |
| Railway | Inside the web service | The service is running |
| Docker | Inside the web container | docker compose ps shows it up |
On the Node platforms, JOBS_IN_PROCESS=false turns the in-process loop off. An external cron must then call pnpm jobs:run. Run that command by hand to see one round's report as JSON. A new deployment records its first round within a minute, so wait a minute before investigating the warning. See Background jobs.
git cannot reach the repository
| Message | Cause | Fix |
|---|---|---|
Repository not found on git clone or git fetch upstream | GitHub answers this for a private repository the account cannot read: the invitation was not accepted, or git is signed in as another account | Accept the invitation in your GitHub notifications, and check which account your SSH key or credential belongs to |
Permission denied (publickey) | No SSH key on this machine is registered with your GitHub account | Add the key to GitHub, or clone over HTTPS with the address on the repository page |
| The invitation link says it has expired | GitHub invitations expire after 7 days | Open Purchased templates (/app/licences) and click Send the invitation again |
fatal: refusing to merge unrelated histories on git merge upstream/main | upstream points at a different template than the one the project was cloned from | Point upstream at the repository you cloned: git remote set-url upstream <address> |
Purchases, activation and refunds are covered in the FAQ.
Verify
After a fix, confirm it by running the checks and repeating the failed action. A saved settings page is not enough:
pnpm typecheck
pnpm validate:gate/setupshows Nothing required is missing.- The action that failed now completes against the real provider: a verification email arrives, a sandbox checkout reaches the provider's page, an upload can be downloaded again.
- Before deploying,
pnpm smoke:node(afterpnpm build:node) orpnpm smoke:worker(afterpnpm build) runs the built server on a throwaway database and checks pages, the agent 503 response and one scheduled round.