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

# Debug Common Auth Issues

> Troubleshoot authentication issues including email codes, verification and password reset emails, session expiration, captcha, custom domains, and OAuth.

Common authentication issues and how to fix them.

<AccordionGroup>
  <Accordion title="Why isn't the email OTP coming through?">
    OTP emails can be blocked by corporate or secure mail servers (common with Outlook and other business email environments), or by email antivirus software at the company level. Here's what to try:

    1. **Check your spam/junk folder** — the email may have been filtered.
    2. **Try a different login method or email** — Google, Apple, or Microsoft sign-in will bypass OTP delivery entirely. If your corporate email is on a secured server, a Gmail or personal address will work immediately.
    3. **Ask your IT team to add our sending domains to your allowlist:**

       * `hercules.app`
       * `notifications.hercules.app`

       This is the most common fix for users on corporate or secured email environments. Once allowlisted, OTPs should come through reliably.
    4. **Email antivirus blocking** — if your company uses email antivirus software, it may be intercepting OTP emails. If you know the name of your provider, share it when you contact us so we can investigate.

    If the issue persists, reach out at [hello@hercules.app](mailto:hello@hercules.app).
  </Accordion>

  <Accordion title="Why isn't a verification or password reset email coming through?">
    1. **Check spam or junk.** Verification and password reset messages can be filtered.
    2. **Confirm the email address.** The password reset screen shows the same confirmation whether
       an account exists or not, so check that the user entered the address on their account.
    3. **Allowlist the sender.** Without a custom sender, allowlist `hercules.app` and
       `notifications.hercules.app`. If you use your own sender, allowlist that domain instead.
    4. **Check your sender identity.** If you configured a custom sender, confirm it is still
       verified under **Email**.

    If the issue persists, reach out at [hello@hercules.app](mailto:hello@hercules.app).
  </Accordion>

  <Accordion title="Why do my users keep getting logged out?">
    Safari's Intelligent Tracking Prevention clears script-writable storage (including the session token) after about 7 days without interaction with your app. This affects Safari on both iOS and macOS, and WebKit-based browsers on iOS. Chrome, Firefox, and Edge on desktop or Android are not affected.

    Ask Hercules to fix it:

    ```text Fix Safari sign-outs wrap theme={}
    Fix the issue where Safari users get signed out every 7 days with the Hercules auth debugging guide.
    ```
  </Accordion>

  <Accordion title="How long do login sessions last?">
    Users stay signed in as long as they open the app at least once every 30 days. Sessions refresh automatically in the background, so active users stay signed in indefinitely.

    If a user does not open the app for 30 days, they will be asked to sign in again.
  </Accordion>

  <Accordion title="Why are my users randomly getting signed out?">
    If users are signed out sooner than 30 days, check these in order:

    1. **Safari or iOS.** See the "Why do my users keep getting logged out?" section above.
    2. **Incognito or private mode, or a browser set to clear site data on close.** The session is wiped when the tab closes.
    3. **New device or browser.** Each browser holds its own session. Signing in somewhere new does not carry over.
    4. **Signed out from somewhere else.** If the user, an admin, or another tab signs out, all of that user's sessions end.
    5. **Something misconfigured in the app's auth setup.** Ask Hercules to check it:

    ```text Check auth setup wrap theme={}
    Check my auth setup against the Hercules Auth debugging guide and fix anything wrong.
    ```

    If none of these fit, click "Support & feedback" with the user's email and roughly when the sign-out happened. The Hercules team can check server logs from there.
  </Accordion>

  <Accordion title="Why is the login captcha not working?">
    Hercules Auth uses Cloudflare Turnstile (a captcha alternative) to verify your users during login. If the verification widget does not load or gets stuck, your users can try these steps:

    1. **Update the browser.** Turnstile supports all major browsers except Internet Explorer. Make sure the browser is up to date.
    2. **Disable browser extensions.** Ad blockers and privacy extensions can block the scripts Turnstile needs. Temporarily disable all extensions and reload the page.
    3. **Confirm JavaScript is enabled.** Turnstile requires JavaScript. Check the browser settings to make sure it is on.
    4. **Try incognito or private mode.** This rules out issues caused by extensions or cached data.
    5. **Test in another browser or device.** This confirms whether the issue is specific to one setup.
    6. **Disable VPNs or proxies.** Some VPNs and proxies interfere with Turnstile. Turn them off temporarily and try again.
    7. **Switch networks.** Some networks block the requests Turnstile needs. Try a mobile hotspot or different Wi-Fi.
    8. **Run the compatibility check.** Open [Cloudflare's Turnstile troubleshooter](https://browser-compat.turnstile.workers.dev/) in the same browser where the issue occurs and share the results when contacting support.

    If none of these steps help, click "Support & feedback" in the sidebar or email [hello@hercules.app](mailto:hello@hercules.app) with a screenshot of the issue and the troubleshooter results.
  </Accordion>

  <Accordion title="My auth domain is not working">
    Make sure the CNAME record is correctly added in your DNS settings. The **Name** field should be `auth`, not the full domain (e.g. not `auth.yourdomain.com`). DNS propagation usually takes a few minutes but can take up to a few hours in rare cases.

    If you use Cloudflare, make sure the CNAME record for the `auth` subdomain is set to **DNS only** (gray cloud icon), not **Proxied** (orange cloud icon). Cloudflare proxying can interfere with the SSL certificate provisioning.

    If it has been more than 24 hours, contact [hello@hercules.app](mailto:hello@hercules.app).
  </Accordion>

  <Accordion title="Users see &#x22;Deceptive site ahead&#x22; or &#x22;Dangerous site&#x22; on my auth domain">
    This is a Google Safe Browsing warning, usually triggered by the apex domain rather than the
    `auth` subdomain itself. See [Google Safe Browsing warnings on your
    domain](/apps/publish/domain-warnings) for the Search Console verification and review request
    flow.
  </Accordion>

  <Accordion title="My Google app is stuck in 'Testing' mode">
    Google OAuth apps start in Testing mode with a 100-user limit. To remove this limit, go to **APIs
    & Services** → **OAuth consent screen** and click **Publish App**. Google may require a
    verification review, which can take several days.
  </Accordion>

  <Accordion title="I lost my Apple private key file">
    Apple only allows you to download the `.p8` private key file once. You will need to create a new
    key in the Apple Developer portal and update the credentials in Hercules. See the [Apple setup
    guide](/apps/users-auth/customize-auth-portal#how-do-i-customize-oauth-branding) for full steps.
  </Accordion>

  <Accordion title="What should I do if auth isn't working?">
    1. Ask Hercules to `configure auth like in the Hercules Auth debugging guide` 2. Accept any
       changes it recommends 3. If the login captcha or verification widget is not loading, see "Why is
       the login captcha not working?" above 4. If still not working, click "Support & feedback" in the
       sidebar and the Hercules team will help
  </Accordion>

  <Accordion title="My users see a 'redirect_uri_mismatch' error">
    This means the Callback URL in the provider's developer console does not match the one Hercules
    uses. Go to your app's **Auth** settings, copy the **Callback URL**, and make sure it is entered
    exactly (including `https://`) in the provider's redirect URI settings. See the [OAuth branding
    guide](/apps/users-auth/customize-auth-portal#how-do-i-customize-oauth-branding) for
    provider-specific steps.
  </Accordion>

  <Accordion title="How long does it take for auth changes to take effect?">
    Changes take effect within about a minute after saving. If you created your OAuth app at the provider, allow a few minutes for the provider to propagate the credentials.
  </Accordion>
</AccordionGroup>