Troubleshooting & upgrading

Most starter problems are local setup drift, not framework bugs. Use this page when the scaffold does not boot, auth fails before you can sign in, or a repo pull leaves your starter docs behind the current template.

Get the starter booting again#

Run the narrow checks in the same order the scaffold expects:

pnpm install --ignore-scripts
kovo check lifecycle
pnpm rebuild
kovo check
kovo test
pnpm run dev

If kovo check fails, fix that before chasing browser behavior. The starter pushes most wiring mistakes into the typed compile path.

Fix missing or placeholder secrets#

create-kovo writes a real local KOVO_CSRF_SECRET into .env and leaves placeholders in .env.example. If you copied .env.example over .env, or deleted the local file, auth and mutations will fail closed.

Use a real secret locally:

openssl rand -base64 32

Then set BETTER_AUTH_SECRET or KOVO_CSRF_SECRET in .env. Leave KOVO_DEMO_PASSWORD set only for local demo sign-in.

Fix sign-in problems#

The starter signs in with demo@example.com plus the generated KOVO_DEMO_PASSWORD from .env. If login fails:

1. Check that .env still contains KOVO_DEMO_PASSWORD.
2. Restart pnpm run dev after changing env vars.
3. Delete the local data file or database volume only if you want to reseed from scratch.

For production, remove the demo password and create real users through your own onboarding path.

Fix docs drift after pulling a newer repo#

The scaffold is the source of truth for onboarding examples. When docs and starter output disagree, compare against:

• packages/create-kovo/templates/src/app.tsx
• packages/create-kovo/templates/src/auth.ts
• packages/create-kovo/templates/README.md

Do not rely on old notes about kovo update-docs; there is no supported scaffold command that rewrites local docs into an existing app.

Upgrade a starter carefully#

When you pull a newer Kovo version, re-check the app-owned files first:

1. src/app.tsx for route, session, and endpoint registration changes.
2. src/auth.ts for auth, CSRF, and Better Auth adapter changes.
3. vite.config.ts and package.json for toolchain command changes.
4. src/components/*.tsx only where you intentionally own copied UI.

Keep your product schema, queries, and mutations. Rebase the scaffold shape around them instead of recreating the app from zero.

Next#

• Project structure - compare your app against the current scaffold layout.
• Better Auth integration - verify the auth/session path in detail.