Troubleshooting
Most setup failures come from missing env vars, mismatched provider secrets, auth redirect gaps, or disabled scheduled jobs.
| Problem | Check first |
|---|---|
| The app does not boot locally | Confirm the core required .env.local values and the pinned Node and pnpm versions. |
| Sign in redirects fail | Check Supabase Site URL and callback URLs for the current domain. |
| Google security email still shows a Supabase hostname | Confirm the app uses Google Identity Services ID-token sign-in, NEXT_PUBLIC_GOOGLE_CLIENT_ID matches the Supabase Google provider, Google Cloud has the product domain and authorized JavaScript origin, and test a new sign-in. Google does not rewrite older notices. |
| Billing setup is not ready | Check provider selection, enabled models, catalog JSON, API key, and webhook secret. |
| Webhook signature is invalid | Use the signing secret from the exact provider endpoint that sends events to the app. |
| Customer history is empty after checkout | Confirm the webhook arrived and the provider event was projected into local billing tables. |
| Email does not send | Check RESEND_API_KEY, sender domain verification, sender email, reply-to email, and send logs. |
| Scheduled work does not run | Check the scheduler URL, method, interval, CRON_SECRET, and Authorization header. |
| Admin cannot see a page | Check role, feature access, dashboard navigation config, and route guard behavior. |