Skip to main content
Common authentication issues and how to fix them.
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.
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:
Fix Safari sign-outs
Fix the issue where Safari users get signed out every 7 days with the Hercules auth debugging guide.
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 in the same browser where the issue occurs and share the results when contacting support.
If none of these steps help, click “Report an issue” in the sidebar or email hello@hercules.app with a screenshot of the issue and the troubleshooter results.
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.
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.
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 for full steps.
  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 “Report an issue” in the sidebar and the Hercules team will help
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 for provider-specific steps.
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.