Troubleshoot local development

The app cannot connect to PostgreSQL

Check DATABASE_URL in the root .env.local, confirm the server is reachable, then run bun run db:push for a disposable local database. Use migrations for shared environments.

Sign-in fails or sessions do not persist

Confirm BETTER_AUTH_SECRET is set and the site's NEXT_PUBLIC_APP_URL (in its .env.development or Vercel project) matches the URL you open in the browser, including the port. Do not set NEXT_PUBLIC_APP_URL in the root .env.local: it overrides every site. If admin portal sign-in never arrives, check BACKEND_ADMIN_EMAILS and, locally, the backend's terminal for the code. For passkeys, PASSKEY_RP_ID must match the domain. See Configure authentication.

A package or build check fails

Reinstall dependencies with bun install, then run the focused workspace build and bun run lint. For maintainer-only failures, consult the internal operations and verification pages.