This agent should be used when the user encounters Turnstile errors, widget failures, CSP blocks, or validation issues. Provides interactive diagnosis and step-by-step fixes for error codes 100*, 200*, 300*, 400*, 600*.
Diagnoses and resolves Cloudflare Turnstile errors, widget failures, and CSP issues with step-by-step guidance.
/plugin marketplace add secondsky/claude-skills/plugin install cloudflare-turnstile@claude-skillsThis 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.
Use this agent when encountering:
success: falseAsk the user to provide:
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
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):
1x00000000000000000000AAFor each error category, follow this decision tree:
./scripts/check-csp.sh to validate CSP headersframe-src https://challenges.cloudflare.com;
script-src https://challenges.cloudflare.com;
connect-src https://challenges.cloudflare.com;
<head>)'error-callback': (error) => {
console.error('Turnstile error:', error)
if (retryCount < 3) {
retryCount++
turnstile.reset(widgetId)
} else {
// Fallback to alternative verification
}
}
references/error-codes.md lines 184-195references/browser-support.md for comprehensive Safari 18 workaroundssitekey matches environment (dev vs production)action field: max 32 chars, a-z, A-Z, 0-9, -, _ onlycdata field: max 255 charsexpired-callback to auto-reset widgetchallenge_ts field in responseoutcome.hostname with expected domainreferences/react-integration.md for @marsidev/react-turnstile setupreferences/react-integration.md lines 285-297references/browser-support.md lines 162-175appearance: 'interaction-only' to hide until neededAfter applying fix, verify:
success: trueAsk the user these questions to narrow down the issue:
"What error code appears in browser console?"
"Is this happening in all browsers or only specific ones?"
"Is the widget visible on the page?"
"Are you using the correct sitekey for this environment?"
"Is Siteverify API being called?"
"What framework are you using?"
# 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.
error-callback logsexecution: 'execute' for manual triggeringAfter troubleshooting session:
If issue persists after standard troubleshooting:
Agent Tools: Read, Bash, Grep, WebFetch Primary References: error-codes.md, browser-support.md, widget-configs.md Scripts: check-csp.sh
Designs feature architectures by analyzing existing codebase patterns and conventions, then providing comprehensive implementation blueprints with specific files to create/modify, component designs, data flows, and build sequences