> ## 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.

    Session length is the same for every sign-in method. Email code, Google, Apple, Microsoft, and single sign-on all end at the same place, so none of them gives a user a longer or shorter session than the others.
  </Accordion>

  <Accordion title="Does the app refresh sign-in tokens on its own?">
    Yes. The app holds a short-lived access token that lasts one hour, and `@usehercules/auth` renews it about a minute before it runs out. Each renewal also brings a new ID token (the token Convex checks to know who the user is), which lasts two and a half hours. You do not need to add anything for this to work.

    Renewal is a direct call to the sign-in service, not a hidden frame, so it does not depend on third-party cookies. That means renewal works the same in a saved home-screen app as it does in a browser tab.

    Keep the sign-in package on one exact version. By default your app can pick up a newer build of `@usehercules/auth` the next time it installs, so two builds of the same app can behave differently. Ask Hercules to lock it:

    ```text Lock the sign-in package version wrap theme={}
    Lock @usehercules/auth to a single exact version so installs cannot pick up a different build.
    ```
  </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.** Signing out ends the current sign-in session, which every tab in that browser shares, so other open tabs are signed out too. That usually happens the next time a tab renews its sign-in, which is within the hour, and takes two and a half hours at most. Sessions on other devices and browsers stay signed in. If you set a new password for a username account, that user is signed out everywhere.
    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="What should I do for users who run the app from the home screen?">
    Saved home-screen apps work with Hercules Auth, and sign-in state lives in the saved app's own storage. Two things come up with saved apps:

    1. **Retry the first call after a long sleep.** A phone can suspend the app for hours, and the renewal timer does not catch up the instant the screen wakes, so the first data call can go out with a token that has already run out. Have that call retry once after a failure rather than showing an error, which gives the renewal time to land. Reloading the page also works, because a reload re-checks an expired token before rendering.
    2. **An update that does not appear on iPhone or iPad means the saved app is running an older copy.** Remove the icon from the home screen, open the site once in Safari, then add it to the home screen again. Android picks up updates on its own.

    Ask Hercules to add the retry:

    ```text Retry the first call after sleep wrap theme={}
    Make the first data call after the app wakes from sleep retry once if it fails, so a token that expired while the phone was asleep has time to renew.
    ```
  </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="My auth domain fails for users in certain countries or networks" id="auth-domain-country-or-network">
    Some users cannot open a custom auth domain such as `auth.yourdomain.com`. The browser shows
    `ERR_CONNECTION_REFUSED` or `ERR_CONNECTION_ABORTED` (the page does not load, or the connection
    stops partway). It can happen several times a day, and a reload sometimes
    gets through. It hits people in a specific country or on a specific internet provider. Your app and your DNS
    setup are not the cause.

    In Spain for example, some internet providers block groups of Cloudflare addresses (the internet addresses
    that deliver the custom auth domain) during LaLiga football matches. The block targets illegal
    streams, and it also takes many unrelated sites offline for a while. Hercules cannot fully
    remove that block.
    [Football matches in Spain knock thousands of sites offline](https://www.euronews.com/2026/09/18/in-spain-football-matches-knock-thousands-of-websites-and-services-offline).

    What you can do:

    1. **App owners:** switch the Auth Portal back to the default `hercules-auth.com` domain. Go to
       **Users & Access** → **Auth Portal** and choose the default domain in the **Auth Portal
       Domain** dropdown. This can help while the block is active.
    2. **Your users:** ask them to try a different network or a VPN, or to retry after some time.
  </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](/docs/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](/docs/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](/docs/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>

  <Accordion title="My OTP code is not working or expired, what do I do?">
    You can request a new OTP code by restarting the login process.
  </Accordion>

  <Accordion title="My users see 'Login error' or 'Load failed' on mobile">
    1. Ask Hercules to `configure auth like in the Hercules Auth debugging guide` 2. Check whether a
       browser extension, antivirus, or network is blocking the connection 3. If everything is correct
       and it still fails, [contact support](/docs/company/contact)
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.