Skip to content
NuxtBase logo NuxtBase Docs

Troubleshooting

This chapter is for when the template is already running or almost running, but something behaves differently from what you expect.

The goal here is not to list every possible bug. It is to help you debug the real failure modes that exist in the NuxtBase template.

Reading Order

Section titled “Reading Order”
Setup Issues Startup env validation errors, placeholder keys, storage config mismatches, and local bootstrap traps.
Auth Issues Login redirects, email verification gates, OAuth callback confusion, and passkey/domain mismatches.
Billing Issues Stripe checkout, missing price IDs, webhook signature failures, and local subscription sync problems.
Email Issues Preview vs SMTP vs Resend behavior, missing API keys, and why emails do not actually send.
Deployment Issues Production-only failures, Coolify memory limits, domain mismatch, and passkey RP ID mistakes.

How To Use This Section

Section titled “How To Use This Section”
  1. start from the symptom you can see
  2. confirm whether the problem happens at startup, on first request, or only in production
  3. check whether the template is falling back to a mock or preview path instead of hard-failing
  4. only change one variable or provider setting at a time

The Most Common Pattern

Section titled “The Most Common Pattern”

Many NuxtBase problems are not caused by a broken feature. They are caused by configuration that is valid enough for the app to boot, but not valid enough for the provider path you expected.

Examples:

  • Stripe key missing: app can still boot, but billing can fall back to mock
  • Resend key missing: app can still boot, but mail may fall back to preview or fail at send time depending on your driver choice
  • AI key left as a fake placeholder: app can still boot, but requests fail when the provider path is actually used