Skip to main content
Something not working? Don’t panic. Most issues come down to a missing env var or a wrong URL. Here’s the quick debugging playbook, followed by fixes for every common problem.

​
Start here

When something breaks, check in this order. It solves 90% of issues:
1

Check your env vars

Missing or misspelled env vars are the #1 cause of issues. Double-check .env.local.
2

Check provider credentials

Make sure your API keys are valid and have the right permissions.
3

Check callback URLs and webhooks

Auth callbacks, payment webhooks, and OAuth redirect URIs must match your actual domain.
4

Check storage config

Many features silently fail without properly configured S3-compatible storage.
5

Check for missing secondary providers

Some features depend on more than one provider (e.g., PDF chat needs both storage AND OpenAI).
Did you restart your dev server after changing .env.local? Next.js doesn’t hot-reload env vars — you need to restart.

​
Common issues

Check these env vars first:
  • BETTER_AUTH_SECRET
  • NEXT_PUBLIC_APP_URL
  • BETTER_AUTH_URL (if you set it)
  • NEXT_PUBLIC_EMAIL_PROVIDER
  • EMAIL_PROVIDER
  • AUTH_EMAIL_FROM
  • GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET
  • NEXT_PUBLIC_GOOGLE_AUTH_ENABLED=true
For Google OAuth specifically:
  • Your callback URL must be /api/auth/callback/google
  • Register both your localhost AND production domain callbacks
  • The domain you’re testing on must match NEXT_PUBLIC_APP_URL
Usually one of these:
  • The provider API key is missing from .env.local
  • The model isn’t listed in lib/ai/models.ts
  • The app doesn’t use that provider path
  • The model has fewer capabilities than you expected (e.g., text but not browsing, text but not vision)
PDF chat depends on multiple things working together:
  • Storage must be configured (S3-compatible)
  • OpenAI embeddings must be available (OPENAI_API_KEY)
  • The document must be uploaded AND indexed
  • The document must be attached to the active chat
If you can upload but don’t get useful citations:
  • Embeddings may not have been created
  • Retrieval may have found no strong matches
  • OpenAI might be missing, so the vector step can’t run
See Storage and Vector RAG for the full setup.
Check your storage env vars:
STORAGE_REGION=...
STORAGE_ACCESS_KEY=...
STORAGE_SECRET_KEY=...
STORAGE_ENDPOINT=...
STORAGE_BUCKET=...
STORAGE_PUBLIC_URL=...
Many app flows depend on file storage. If storage isn’t configured, the apps will load but uploads and saved outputs will silently fail.
Check:
  • NEXT_PUBLIC_PAYMENT_PROVIDER matches your active provider
  • Provider webhook secret is set correctly
  • Webhook URL is correct: /api/payments/stripe, /api/payments/lemonsqueezy, or /api/payments/polar
  • Hosted checkout URLs are pointing to real products
  • Product/variant mapping is configured (via metadata or env map)
If checkout works but nothing happens after payment, the webhook is usually the issue. The webhook is what tells your app the payment actually happened.
Check:
  • NEXT_PUBLIC_ANALYTICS_PROVIDER — spelled correctly?
  • Provider-specific env vars (PostHog key, Plausible domain, DataFast ID)
  • Did you restart the dev server?
For multiple providers, use a comma-separated value:
NEXT_PUBLIC_ANALYTICS_PROVIDER=posthog,datafast
Voice Studio has several separate API paths: voices, text-to-speech, speech-to-speech, music, and sound effects.If one mode works and another fails, the whole app isn’t broken — check the specific mode’s requirements and your ElevenLabs access level for that feature.
This is usually a branding/content issue, not a runtime bug. Check:
  • config.ts — site name, URLs, links
  • Landing page copy and pricing sections
  • App descriptions and metadata
  • Docs content
Since the repo includes both product and marketing surfaces, outdated copy in one place can make everything feel inconsistent.
Make sure:
  • Mintlify is pointed at the anotherwrapper-premium repo
  • The docs root is set to docs/public
  • The nav in docs/public/mint.json matches the files that actually exist

Configuration

Review all env vars and config surfaces.

Launch Checklist

Full pre-launch verification checklist.