Setup Issues

Use this page when the app fails early, boots with the wrong provider behavior, or behaves differently from what the setup docs describe.

The First Split To Make

Before changing anything, decide which of these two states you are in:

1. the server does not start
2. the server starts, but a provider path is wrong at runtime

Those are different classes of problems in NuxtBase.

Problem: The Server Fails At Startup With Env Errors

If startup fails immediately, the template is usually rejecting the shape of your environment variables.

Typical error shape:

Invalid environment variables:
DATABASE_URL: ...
GOOGLE_CLIENT_ID: GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set together

What NuxtBase Actually Validates At Startup

The env parser does strict validation for:

• DATABASE_URL
• BETTER_AUTH_SECRET
• BETTER_AUTH_URL
• NUXT_PUBLIC_SITE_URL
• OAuth client ID and secret pairs
• SMTP username and password pairs
• full S3/R2 credential sets when storage is not local

What To Check

1. read the full startup error instead of fixing one variable blindly
2. look for pair-based errors first, especially Google, GitHub, and SMTP
3. if storage is s3 or r2, confirm that all six S3 variables exist together
4. restart the app after each env change so Nitro reloads the latest values

Problem: You Copied .env.example, Skipped A Provider, But The App Still Tries To Use It

This is one of the easiest traps to hit.

After copying .env.example, placeholder values like sk_test_... or sk-... are still non-empty strings. In the template, non-empty provider keys often mean “enable this provider path”.

That means:

• fake Stripe keys can make billing initialize Stripe instead of mock billing
• fake OpenAI keys can make AI requests use the OpenAI branch instead of acting like AI is disabled

Fix

If you are not using a provider yet, remove the placeholder value completely, comment it out, or leave it blank.

# Good: disabled for now
NUXT_STRIPE_SECRET_KEY=
NUXT_OPENAI_API_KEY=

Caution

Do not treat a fake placeholder key as “disabled”. In this template, an incorrect non-empty value often selects the real provider path.

Problem: Storage Fails After Switching To s3 Or r2

If NUXT_STORAGE_PROVIDER is set to s3 or r2, startup validation expects the full storage credential set to exist.

Typical causes:

• missing S3_PUBLIC_URL
• missing endpoint or region
• access key and secret not set together in the deployed environment

In the normal template path, missing remote-storage credentials are usually blocked at startup, not later during upload requests.

Typical startup error shape:

Invalid environment variables:
NUXT_STORAGE_PROVIDER: S3_BUCKET, S3_REGION, S3_ENDPOINT, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, and S3_PUBLIC_URL are required when NUXT_STORAGE_PROVIDER is s3 or r2

Fix

Verify all of these together:

• S3_BUCKET
• S3_REGION
• S3_ENDPOINT
• S3_ACCESS_KEY_ID
• S3_SECRET_ACCESS_KEY
• S3_PUBLIC_URL

If you do not want remote object storage yet, switch back to:

NUXT_STORAGE_PROVIDER=local

Do Not Confuse This With Invalid storage key

Invalid storage key is a different problem. In the current template, that error is part of storage-key safety checks, not the usual missing-credentials path for s3 or r2.

Problem: INITIAL_ADMIN_EMAIL Does Nothing

INITIAL_ADMIN_EMAIL is a bootstrap convenience, not a user creator.

If no matching user already exists, the server logs a warning and skips the admin grant.

Fix

1. register the user first
2. make sure the email matches exactly
3. restart the server so the bootstrap plugin runs again

If you need a deterministic fix, use the dedicated admin grant command described in the admin docs instead of relying only on bootstrap.

Problem: The App Starts, So You Assume Setup Is Finished

This assumption causes a lot of wasted debugging time.

NuxtBase can boot successfully even when some providers are only partially configured. Billing, AI, and email are not all enforced in the same way at startup.

Use this rule:

• startup success proves the env shape is acceptable
• feature testing proves the provider is actually usable

Run one real smoke test per provider after setup:

• sign in with the auth method you enabled
• send a real or preview email
• create one Stripe checkout session
• upload one file
• send one AI message