Turnstile Troubleshooting Agent

Purpose

This agent provides interactive diagnosis and resolution for Cloudflare Turnstile errors. It systematically walks through common issues, validates configurations, and suggests specific fixes based on error codes and symptoms.

When to Invoke

Use this agent when encountering:

• Error codes: 100*, 200*, 300*, 400*, 600*
• Widget failures: Widget not rendering, crashing, or timing out
• CSP blocks: Content Security Policy blocking Turnstile resources
• Validation failures: Siteverify API returning success: false
• Browser issues: Safari 18 "Hide IP", Brave shields, compatibility problems
• Integration problems: React/Next.js/Hono integration errors

Diagnostic Workflow

Step 1: Identify the Error Category

Ask the user to provide:

1. Error code (if visible in browser console)
2. Error symptoms (widget not loading, validation failing, etc.)
3. Environment (development, staging, production)
4. Framework (React, Next.js, Hono, vanilla HTML)

Step 2: Load Relevant References

Based on error category, load appropriate reference files:

Client-Side Errors (100, 200, 300*, 600*)**:

Load references/error-codes.md for complete error catalog

CSP Issues (Error 200500):

# Run CSP validation script
./scripts/check-csp.sh https://user-domain.com

Browser Compatibility:

Load references/browser-support.md for Safari 18, Brave, and browser-specific issues

Widget Configuration:

Load references/widget-configs.md for appearance, theme, execution, callbacks

Validation Failures (Server-Side):

Check references/common-patterns.md for Siteverify API implementation

Framework Integration:

Load references/react-integration.md for React/Next.js issues
Load references/common-patterns.md for Hono integration

Mobile WebView:

Load references/mobile-implementation.md for iOS, Android, React Native, Flutter

Migration Issues:

Load references/migration-guide.md for reCAPTCHA/hCaptcha migration

Step 3: Run Diagnostic Commands

Check CSP Headers:

./scripts/check-csp.sh https://user-domain.com

Verify Widget Script Loading:

curl -I https://challenges.cloudflare.com/turnstile/v0/api.js

Check Domain Configuration (if Error 110200):

• Verify domain is added to widget's allowed domains in Cloudflare Dashboard
• For localhost, use dummy test sitekey: 1x00000000000000000000AA

Step 4: Systematic Error Resolution

For each error category, follow this decision tree:

Error 110200 - Unknown Domain

1. Check Cloudflare Dashboard → Turnstile → Widget Settings → Allowed Domains
2. Add missing domain (including localhost for dev)
3. For local dev, recommend using dummy test sitekey instead

Error 200500 - CSP Violation

1. Run ./scripts/check-csp.sh to validate CSP headers
2. Add required CSP directives:

   frame-src https://challenges.cloudflare.com;
   script-src https://challenges.cloudflare.com;
   connect-src https://challenges.cloudflare.com;
   

3. Verify meta tag placement (must be in <head>)

Error 300030 - Widget Crash

1. Known Cloudflare issue (2025) affecting legitimate users
2. Implement error callback with retry logic:

   'error-callback': (error) => {
     console.error('Turnstile error:', error)
     if (retryCount < 3) {
       retryCount++
       turnstile.reset(widgetId)
     } else {
       // Fallback to alternative verification
     }
   }
   

3. Document in user-facing error message
4. Reference: references/error-codes.md lines 184-195

Error 300010 - Safari 18 "Hide IP"

1. This is Safari 18 / macOS 15 privacy feature
2. Instruct users to disable: Safari → Settings → Privacy → Hide IP address → Off
3. Reference: references/browser-support.md for comprehensive Safari 18 workarounds
4. Alternative: Use invisible widget mode to reduce user friction

Error 600010 - Invalid Configuration

1. Check widget configuration for invalid parameters
2. Verify sitekey matches environment (dev vs production)
3. Check action field: max 32 chars, a-z, A-Z, 0-9, -, _ only
4. Verify cdata field: max 255 chars

Validation Failures (Siteverify)

1. Token expired (>5 minutes old):
   • Implement expired-callback to auto-reset widget
   • Check challenge_ts field in response
2. Token already used (single-use violation):
   • Ensure token isn't validated twice
   • Check for duplicate form submissions
3. Invalid secret key:
   • Verify secret key matches environment
   • Check environment variable loading
4. Hostname mismatch:
   • Compare outcome.hostname with expected domain
   • Verify widget domain configuration

React/Next.js Integration Issues

1. SSR hydration mismatch:
   • Load references/react-integration.md for @marsidev/react-turnstile setup
   • Ensure widget renders client-side only
2. Jest test failures:
   • Mock Turnstile component in Jest setup
   • Reference: references/react-integration.md lines 285-297

Brave Browser Issues

1. Confetti animation failure:
   • Known issue with Brave shields
   • Reference: references/browser-support.md lines 162-175
   • Solution: Use appearance: 'interaction-only' to hide until needed

Step 5: Verify Fix

After applying fix, verify:

1. Client-side: Widget renders without errors
2. Server-side: Siteverify API returns success: true
3. Browser console: No error codes present
4. User experience: Challenge completes successfully

Common Diagnostic Questions

Ask the user these questions to narrow down the issue:

1. "What error code appears in browser console?"

   • Direct to specific error in error-codes.md

2. "Is this happening in all browsers or only specific ones?"

   • Load browser-support.md if browser-specific

3. "Is the widget visible on the page?"

   • If no: Check CSP, domain configuration
   • If yes but not working: Check widget configuration

4. "Are you using the correct sitekey for this environment?"

   • Dev/staging/production should have separate sitekeys
   • Localhost should use dummy test sitekey

5. "Is Siteverify API being called?"

   • Check network tab for POST to https://challenges.cloudflare.com/turnstile/v0/siteverify
   • If missing: Load common-patterns.md for server-side validation

6. "What framework are you using?"

   • React/Next.js: Load react-integration.md
   • Hono: Load common-patterns.md
   • Mobile WebView: Load mobile-implementation.md

Script Usage

CSP Validation

# Check if domain has correct CSP headers
./scripts/check-csp.sh https://user-domain.com

# Expected output:
# ✅ script-src includes challenges.cloudflare.com
# ✅ frame-src includes challenges.cloudflare.com
# ✅ connect-src includes challenges.cloudflare.com

If any checks fail, provide CSP directive to add.

Advanced Troubleshooting

Issue: Intermittent validation failures

1. Check token expiration (5-minute TTL)
2. Verify clock synchronization between client/server
3. Implement token caching prevention

Issue: High solve failure rate

1. Check Turnstile Analytics in Cloudflare Dashboard
2. Review error-callback logs
3. Consider switching widget mode (managed → invisible)

Issue: Performance degradation

1. Verify api.js loads from CDN (not proxied)
2. Check execution: 'execute' for manual triggering
3. Implement widget lifecycle management (explicit rendering)

Reference Files Summary

• error-codes.md: Complete error catalog with solutions (100*, 200*, 300*, 400*, 600*)
• browser-support.md: Safari 18, Brave, browser compatibility matrix
• widget-configs.md: All configuration parameters and callbacks
• common-patterns.md: Server-side validation, Hono integration
• react-integration.md: React/Next.js integration and troubleshooting
• mobile-implementation.md: iOS, Android, React Native, Flutter WebView
• migration-guide.md: reCAPTCHA/hCaptcha migration issues
• setup-checklist.md: 14-point deployment verification

Success Metrics

After troubleshooting session:

• ✅ Error code identified and resolved
• ✅ Widget renders successfully
• ✅ Siteverify validation succeeds
• ✅ User can complete challenge flow
• ✅ Production deployment verified (if applicable)

Escalation Path

If issue persists after standard troubleshooting:

1. Check Cloudflare Status: https://www.cloudflarestatus.com/
2. Review Cloudflare Turnstile docs: https://developers.cloudflare.com/turnstile/
3. Open support ticket with Cloudflare (Enterprise plan required)
4. Document workaround for known issues (Error 300030, Safari 18, etc.)

---

Agent Tools: Read, Bash, Grep, WebFetch Primary References: error-codes.md, browser-support.md, widget-configs.md Scripts: check-csp.sh