Troubleshooting

Common issues and how to resolve them.

Enable Debug Mode

First, enable debug mode to see detailed error messages:

javascript

gkCaptcha.render('container', {
  siteKey: 'your-site-key',
  debug: true, // Enable console logging
  onError: (error) => {
    console.error('CAPTCHA Error:', error);
  }
});

Common Issues

Widget Not Loading

The widget container remains empty or shows nothing.

Check 1: Script loaded?

Open browser DevTools > Network tab. Verify widget.js loaded successfully (200 status).

Check 2: Container exists?

Ensure the container element exists in DOM before calling render(). Use DOMContentLoaded or place script at end of body.

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;
">

Invalid Site Key Error

Console shows "Invalid site key" or "Site not found".

Solution:

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

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

javascript

// Increase timeout for slow connections
const result = await fetch('https://gkcaptcha.gatekeeper.sa/api/v1/token/verify', {
  method: 'POST',
  headers: { ... },
  body: JSON.stringify({ token }),
  signal: AbortSignal.timeout(15000) // 15 seconds
});

Token Expired or Already Used

Verification fails with "timeout-or-duplicate" error.

Causes:

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

Solution: Handle expiration

javascript

let currentToken = null;
let tokenTimestamp = null;

gkCaptcha.render('container', {
  siteKey: 'your-site-key',
  onSuccess: (token) => {
    currentToken = token;
    tokenTimestamp = Date.now();
  },
  onExpired: () => {
    currentToken = null;
    tokenTimestamp = null;
    showMessage('Please verify again');
  }
});

// Before form submission
function submitForm() {
  // Check if token is still fresh (< 5 minutes)
  if (!currentToken || Date.now() - tokenTimestamp > 5 * 60 * 1000) {
    showError('Verification expired. Please verify again.');
    widget.reset();
    return;
  }
  // Submit with token...
}

Multiple Widgets Appearing

Widget duplicates on page navigation or hot reload.

Solution:

javascript

// WRONG - Multiple render calls create duplicates
gkCaptcha.render('container', { siteKey: 'key' });
gkCaptcha.render('container', { siteKey: 'key' }); // Duplicate!

// CORRECT - Check if already rendered
if (!document.querySelector('#container .gk-captcha-widget')) {
  gkCaptcha.render('container', { siteKey: 'key' });
}

// OR - Reset existing widget
const widget = gkCaptcha.render('container', { siteKey: 'key' });
// Later...
widget.reset(); // Resets instead of creating new

React/Next.js Hydration Errors

Console shows hydration mismatch or widget renders twice.

Solution: Proper cleanup

tsx

// WRONG - Renders during SSR
export function Form() {
  useEffect(() => {
    gkCaptcha.render('container', { siteKey: 'key' });
  }, []); // Missing cleanup!
}

// CORRECT - With cleanup and hydration safety
export function Form() {
  const containerRef = useRef<HTMLDivElement>(null);
  const widgetRef = useRef<any>(null);

  useEffect(() => {
    if (containerRef.current && !widgetRef.current) {
      widgetRef.current = gkCaptcha.render(containerRef.current, {
        siteKey: 'key'
      });
    }

    return () => {
      if (widgetRef.current) {
        widgetRef.current.destroy();
        widgetRef.current = null;
      }
    };
  }, []);

  return <div ref={containerRef} />;
}

Error Codes Reference

Error Code	Meaning	Solution
E001	Invalid site key	Check site key in dashboard
E002	Domain not allowed	Add domain to site settings
E003	Token expired	Reset widget and retry
E004	Token already used	Get fresh token before each submit
E005	Invalid secret key	Check secret key in server config
E006	Rate limited	Wait and retry, or upgrade plan
E007	Network error	Check connectivity to API

Still Need Help?

If you are still experiencing issues:

Enable debug mode and check console errors
Review the Network tab for failed requests
Check our status page for outages
Contact support at support@gatekeeper.sa

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