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

# Troubleshooting

> Fix common Nudgra setup issues with Google OAuth, Meta webhooks, Caddy, and account connection.

Use these checks when sign-in, deployment, webhooks, or account connection does not work.

## Google sign-in says the account is not allowed

<Tabs>
  <Tab title="Nudgra OSS">
    Check that the exact Google email is listed in `.env`:

    ```env theme={null}
    OPERATOR_EMAIL_ALLOWLIST=you@example.com
    ```

    Restart after changing `.env`:

    ```bash theme={null}
    docker compose up -d --build
    ```
  </Tab>

  <Tab title="Nudgra Cloud">
    Check the Convex production allowlist:

    ```bash theme={null}
    npx convex env list --prod
    ```

    Set or update the allowlist:

    ```bash theme={null}
    npx convex env set --prod NUDGRA_ALLOWED_EMAILS you@example.com,backup@example.com
    ```
  </Tab>
</Tabs>

## Google login redirects to the wrong URL

<Tabs>
  <Tab title="Nudgra OSS">
    Make sure all app origins match the real domain:

    ```env theme={null}
    SITE_URL=https://your-domain.com
    BETTER_AUTH_URL=https://your-domain.com
    TRUSTED_ORIGINS=https://your-domain.com
    ```

    Verify the Google OAuth redirect URI:

    ```text theme={null}
    https://your-domain.com/api/auth/callback/google
    ```
  </Tab>

  <Tab title="Nudgra Cloud">
    Check:

    ```env theme={null}
    SITE_URL=https://your-app-domain.com
    ```

    Verify that Google uses the Convex site URL:

    ```text theme={null}
    https://your-convex-site.convex.site/api/auth/callback/google
    ```

    Do not use:

    ```text theme={null}
    https://your-app-domain.com/api/auth/callback/google
    ```
  </Tab>
</Tabs>

## Meta webhook verification fails

<Tabs>
  <Tab title="Nudgra OSS">
    Check:

    * `META_VERIFY_TOKEN` in `.env` exactly matches the token entered in Meta.
    * `https://your-domain.com/api/meta/webhooks` is reachable publicly.
    * The app was restarted after `.env` changes.
    * The Meta app is published.
    * The subscribed fields are `messages`, `messaging_postbacks`, and `comments`.

    Useful commands:

    ```bash theme={null}
    curl -i https://your-domain.com/api/meta/webhooks
    docker compose logs -f app
    ```
  </Tab>

  <Tab title="Nudgra Cloud">
    Check:

    * `META_VERIFY_TOKEN` in Convex exactly matches the token entered in Meta.
    * `https://your-convex-site.convex.site/meta/webhooks` is reachable publicly.
    * Convex has been redeployed after code changes.
    * The Meta app is published.
    * The subscribed fields are `messages`, `messaging_postbacks`, and `comments`.

    Useful commands:

    ```bash theme={null}
    npx convex logs --prod
    npx convex env list --prod
    ```
  </Tab>
</Tabs>

A plain browser request to the webhook URL may return `403` because it is missing Meta verification query parameters. That still proves the route is reachable. Meta's **Verify and save** button is the real webhook verification.

## Meta webhooks are verified but no events appear

Check:

* The webhook callback URL points to the correct target for your distribution.
* The connected Instagram account accepted the tester invite during development.
* The app has the required Instagram permissions.
* The app is in Live mode for real users.
* The Instagram account is professional, business or creator.
* The connected account still appears active in the account page.

<Warning>
  For Nudgra Cloud, the webhook callback URL is the Convex URL. For Nudgra OSS, it is the app URL.
</Warning>

## Instagram account does not appear during connection

Check:

* The Instagram account accepted the tester invite.
* The invite was accepted from Instagram on desktop.
* The app has the required Instagram permissions.
* The Instagram account is professional, business or creator.
* You are logged into the correct Instagram account when authorizing.
* The app `SITE_URL` matches the Meta redirect URL exactly.

## Caddy says `address already in use`

On a Nudgra OSS VPS, check what owns ports `80` and `443`:

```bash theme={null}
sudo ss -tulpn | grep -E ':80|:443'
```

If another Caddy site is already bound to a public IP, use `bind YOUR_VPS_PUBLIC_IP` in the Nudgra site block.

If Nginx is running and you do not use it, stop it:

```bash theme={null}
sudo systemctl stop nginx
sudo systemctl disable nginx
```

## Mutations fail with `Forbidden origin`

For Nudgra OSS, add the exact origin to `TRUSTED_ORIGINS`:

```env theme={null}
TRUSTED_ORIGINS=https://your-domain.com
```

Then restart:

```bash theme={null}
docker compose up -d --build
```

## Tracked links use the wrong host

<Tabs>
  <Tab title="Nudgra OSS">
    Check:

    ```env theme={null}
    SITE_URL=https://your-domain.com
    ```

    Restart after changing `.env`.
  </Tab>

  <Tab title="Nudgra Cloud">
    Check Convex production:

    ```bash theme={null}
    npx convex env get --prod SITE_URL
    ```

    Set it to the public app domain:

    ```bash theme={null}
    npx convex env set --prod SITE_URL https://your-app-domain.com
    ```

    Redeploy after changing hosted settings.
  </Tab>
</Tabs>