Troubleshooting

Common issues and how to resolve them.

Check the Console First

The widget reports every setup problem in the browser console as a [gkCAPTCHA] error that names the fix.

Common Issues

1

Widget Not Loading

The widget container remains empty or shows nothing.

Check 1: Script loaded?

Open DevTools > Network. Check that gk-captcha.js loaded with status 200.

Check 2: Waiting for the element?

The script loads with async, so it may run after your code. Before you call a method, wait for customElements.whenDefined('gk-captcha').

Check 3: CSP blocking?

Check console for Content Security Policy errors. Add our domains:

html
<meta http-equiv="Content-Security-Policy" content="
  script-src 'self' https://gkcaptcha.gatekeeper.sa;
  connect-src 'self' https://gkcaptcha.gatekeeper.sa;
  frame-src 'self' https://gkcaptcha.gatekeeper.sa;
">
2

Invalid Site Key Error

The console shows a [gkCAPTCHA] error about the site key, or captcha-error fires with invalid-site-key.

Solution:

  • Use the attribute sitekey. The widget does not read site-key or data-sitekey.
  • Verify you are using the Site Key (starts with pk_), not the Secret Key
  • Check for extra spaces or quotes in the key
  • Ensure the site is active in your dashboard
  • Verify the domain matches your site settings
3

Verification Timeout

Server-side verification returns timeout or connection errors.

Solutions:

  • Increase request timeout to 15+ seconds
  • Check server can reach gkcaptcha.gatekeeper.sa
  • Verify firewall allows outbound HTTPS
4

Token Expired or Already Used

Server verification returns "invalid or expired token" or "token already used".

Causes:

  • Tokens expire after 5 minutes
  • Each token can only be verified once
  • User took too long to submit form

Solution: Handle expiration

app.js
const form = document.querySelector('#signup-form');
const captcha = document.createElement('gk-captcha');
captcha.setAttribute('sitekey', 'pk_live_...');
captcha.setAttribute('mode', 'invisible');
form.appendChild(captcha);

form.addEventListener('submit', async (event) => {
  event.preventDefault();
  try {
    await customElements.whenDefined('gk-captcha');
    await captcha.getToken(); // also fills the gk-captcha-token field
    // URL-encoded, so a standard express.urlencoded() server reads req.body['gk-captcha-token'].
    await fetch(form.action, { method: 'POST', body: new URLSearchParams(new FormData(form)) });
  } catch (error) {
    // Show an error message. Never send the form without a token.
  } finally {
    captcha.reset(); // each token works once
  }
});
5

Multiple Widgets Appearing

Each gk-captcha element is one widget, so two elements make two widgets.

Solution:

Add the element once per form. When your page or framework removes the element, the widget stops all its work.

6

React/Next.js Hydration Errors

Console shows hydration mismatch or widget renders twice.

Solution: use the React package

Use @gkcaptcha/react. It loads the script once and removes the widget when the component unmounts.

Error Codes Reference

The widget reports one of six codes in e.detail.code. The full list, with what to do for each, is on the widget page.

Still Need Help?

If you are still experiencing issues:

  1. Check the browser console for [gkCAPTCHA] errors
  2. Review the Network tab for failed requests
  3. Check our status page for outages
  4. Contact support at support@gatekeeper.sa

When contacting support, please include: error codes, browser/OS info, and steps to reproduce.