Troubleshooting

Common issues and their fixes.

Auth returns 500 on sign-in / sign-up

The auth layer depends on a pinned kysely version. If you bumped it (directly or transitively), auth requests can 500. Pin kysely back to the version the template ships, reinstall, and restart.

db:push / db:studio can’t find the database

drizzle-kit reads from .env.local, not .env. Make sure DATABASE_URL is in .env.local. Also confirm Postgres is up:

docker compose up -d

Connection refused / port 5432 already in use

The bundled Postgres uses host port 5432 by default, matching .env.example. If another Postgres already holds 5432, the container fails to bind. Remap it and update DATABASE_URL to match:

POSTGRES_PORT=5433 docker compose up -d

Then set DATABASE_URL to use localhost:5433.

Dev server isn’t on port 3000

If 3000 is taken, Next.js falls back to another port (often 3002). Check the startup log for the actual URL.

Stripe checkout succeeds but the plan never updates

The plan only changes when a webhook reaches /api/billing/webhook. The usual cause is a Stripe CLI bound to the wrong account. Always pass your app’s key:

stripe listen --api-key "$STRIPE_SECRET_KEY" \
  --forward-to localhost:3000/api/billing/webhook

In production, confirm the dashboard webhook endpoint and STRIPE_SECRET_KEY belong to the same account. See Stripe in production.

”Subscription cannot be updated” when switching plans

The customer portal’s subscription-update feature is disabled. Enable it and list your Pro/Team products — see Stripe in production.

Verification email never arrives

In development the default EMAIL_PROVIDER=console prints links to the terminal instead of sending email. Check your dev server logs. For real delivery, switch to Resend — see Email.

AI calls are blocked

You’ve likely hit a plan limit (monthly tokens or messages). Check usage, upgrade the plan, or raise the limits in plans.ts.

OAuth redirects to localhost in production

Set BETTER_AUTH_URL and NEXT_PUBLIC_BETTER_AUTH_URL to your production domain, and re-register OAuth callback URLs with each provider to match.