> ## Documentation Index
> Fetch the complete documentation index at: https://docs.anotherwrapper.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Quick fixes for the most common issues — you'll be back on track in minutes

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:

<Steps>
  <Step title="Check your env vars">
    Missing or misspelled env vars are the #1 cause of issues. Double-check `.env.local`.
  </Step>

  <Step title="Check provider credentials">
    Make sure your API keys are valid and have the right permissions.
  </Step>

  <Step title="Check callback URLs and webhooks">
    Auth callbacks, payment webhooks, and OAuth redirect URIs must match your actual domain.
  </Step>

  <Step title="Check storage config">
    Many features silently fail without properly configured S3-compatible storage.
  </Step>

  <Step title="Check for missing secondary providers">
    Some features depend on more than one provider (e.g., PDF chat needs both storage AND OpenAI).
  </Step>
</Steps>

<Tip>
  Did you restart your dev server after changing `.env.local`? Next.js doesn't hot-reload env vars — you need to restart.
</Tip>

## Common issues

<AccordionGroup>
  <Accordion title="Auth emails or Google login not working">
    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`
  </Accordion>

  <Accordion title="Magic link sends but login doesn't complete">
    This is almost always a **redirect mismatch**. Check:

    * `NEXT_PUBLIC_APP_URL`
    * `BETTER_AUTH_URL` (if you use it)
    * The domain you clicked the link on
    * The callback URL encoded in the email link

    <Warning>
      Better Auth verifies callback and origin handling inside the app. If the auth link points to a different origin than the one you're using, sign-in will start but never finish.
    </Warning>
  </Accordion>

  <Accordion title="Password reset or magic link emails not arriving">
    Check:

    * `NEXT_PUBLIC_EMAIL_PROVIDER` — must be `loops`, `resend`, or `brevo` if you expect those auth modes in the UI
    * `EMAIL_PROVIDER` — must be `loops`, `resend`, or `brevo` (not `none`)
    * `AUTH_EMAIL_FROM` — required for all auth emails
    * The provider API key for whichever provider you chose

    Provider-specific gotchas:

    * **Loops** also needs `LOOPS_AUTH_MAGIC_LINK_TRANSACTIONAL_ID` and `LOOPS_AUTH_RESET_PASSWORD_TRANSACTIONAL_ID`
    * **Resend** and **Brevo** just need the provider key + `AUTH_EMAIL_FROM`
    * `EMAIL_PROVIDER=none` completely disables outbound auth emails
  </Accordion>

  <Accordion title="A model doesn't show up in the UI">
    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)
  </Accordion>

  <Accordion title="PDF chat isn't working">
    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

    <Info>
      See [Storage](/services/storage) and [Vector RAG](/services/vector-rag) for the full setup.
    </Info>
  </Accordion>

  <Accordion title="Image, video, voice, or vision uploads fail">
    Check your storage env vars:

    ```env theme={null}
    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.
  </Accordion>

  <Accordion title="Payments go through but purchases don't appear">
    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)

    <Tip>
      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.
    </Tip>
  </Accordion>

  <Accordion title="Analytics not firing">
    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:

    ```env theme={null}
    NEXT_PUBLIC_ANALYTICS_PROVIDER=posthog,datafast
    ```
  </Accordion>

  <Accordion title="Voice Studio loads but some modes fail">
    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.
  </Accordion>

  <Accordion title="App looks outdated or mismatched">
    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.
  </Accordion>

  <Accordion title="Mintlify docs preview looks wrong">
    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
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Configuration" icon="settings" href="/configuration">
    Review all env vars and config surfaces.
  </Card>

  <Card title="Launch Checklist" icon="rocket" href="/launch-checklist">
    Full pre-launch verification checklist.
  </Card>
</CardGroup>