gh-jezweb-claude-skills-skills-cloudflare-turnstile/references/error-codes.md

Turnstile Error Codes Reference

Complete error code reference with troubleshooting

Official Docs: https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/error-codes/

---

Error Code Families

Error codes use the format XXXYYY where:

• XXX = Error family (indicates general category)
• YYY = Specific error (internal use, often marked *** in docs)

Note: When *** appears, the last 3 digits can be ignored.

---

100*** - Initialization Problems

Error: Problem initializing Turnstile before challenge could start

Retry: No

Cause: Usually caused by:

• Old instance of solved challenge still present
• Page state corruption
• Cache issues

Solution:

1. Reload the page
2. Clear browser cache
3. Reset Turnstile widget programmatically
4. On continuous failures → likely automated device

---

102***, 103***, 104***, 106*** - Invalid Parameters

Error: Visitor sent invalid parameter as part of challenge

Retry: Yes

Cause:

• Malformed request data
• Corrupted challenge parameters
• Browser/extension interference

Solution:

1. Retry the challenge automatically
2. On continuous failures → likely bot
3. Implement error-callback with retry logic
4. Verify visitor authenticity by other means

---

105*** - API Compatibility

Error: Turnstile invoked in deprecated or invalid way

Retry: No

Cause:

• Using outdated API methods
• Invalid widget configuration
• Script version mismatch

Solution:

1. Check official Turnstile documentation
2. Refresh page to get latest script version
3. Review widget initialization code
4. Ensure api.js loads from Cloudflare CDN

---

110100, 110110 - Invalid Sitekey

Error: Turnstile invoked with invalid or inactive sitekey

Retry: No

Cause:

• Sitekey doesn't exist
• Sitekey was deleted
• Typo in sitekey
• Using wrong sitekey for environment

Solution:

1. Verify sitekey in Cloudflare Dashboard
2. Check sitekey is still active
3. Ensure no typos in configuration
4. Use correct sitekey for environment (dev/prod)

Example:

// ❌ Wrong
const SITE_KEY = '1x00000000000000000000AA' // Test key in production

// ✅ Correct
const SITE_KEY = process.env.TURNSTILE_SITE_KEY

---

110200 - Unknown Domain

Error: Domain not allowed for this widget

Retry: No

Cause:

• Current hostname not in widget's allowed domains list
• Using production widget on localhost
• Subdomain not added to allowlist

Solution:

1. Add domain to allowed list in Cloudflare Dashboard
2. For localhost: add localhost or use test sitekey 1x00000000000000000000AA
3. Check subdomain matches exactly (www.example.com ≠ example.com)

Example Allowed Domains:

example.com
www.example.com
localhost        # For development
127.0.0.1        # For development

---

110420 - Invalid Action

Error: Unsupported or incorrectly formatted action submitted

Retry: No

Cause:

• Action contains invalid characters
• Action exceeds 32 character limit
• Non-alphanumeric characters (except - and _)

Solution:

1. Use only a-z, A-Z, 0-9, -, _
2. Keep action ≤ 32 characters
3. Example valid actions: login, signup, contact-form

Reference: https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#configurations

---

110430 - Invalid cData

Error: Custom data (cData) format invalid

Retry: No

Cause:

• cData contains invalid characters
• cData exceeds 255 character limit

Solution:

1. Keep cData ≤ 255 characters
2. Use JSON.stringify() for objects
3. Validate data before passing to Turnstile

Example:

// ❌ Wrong - too long
const cdata = JSON.stringify({ /* 300+ chars */ })

// ✅ Correct
const cdata = JSON.stringify({ userId: '123', sessionId: 'abc' })

---

110500 - Unsupported Browser

Error: Visitor using unsupported browser

Retry: No

Cause:

• Internet Explorer (not supported)
• Very outdated browser version
• Browser without required APIs

Solution:

1. Encourage visitor to upgrade browser
2. Provide alternative verification method
3. Display browser upgrade message

Supported Browsers: https://developers.cloudflare.com/cloudflare-challenges/reference/supported-browsers/

---

110510 - Inconsistent User-Agent

Error: Visitor provided inconsistent user-agent during challenge

Retry: No

Cause:

• Browser extensions spoofing user-agent
• Privacy tools modifying headers
• Browser settings

Solution:

1. Ask visitor to disable user-agent spoofing extensions
2. Disable privacy tools temporarily
3. Try different browser

---

11060* - Challenge Timed Out

Error: Visitor took too long to solve challenge

Retry: Yes

Cause:

• Slow network connection
• System clock set incorrectly
• Visitor distracted/inactive

Solution:

1. Retry the challenge
2. Check system clock is correct
3. Improve network connection

---

11062* - Interactive Challenge Timeout

Error: Visitor didn't interact with checkbox (visible mode only)

Retry: Yes

Cause:

• Challenge became outdated while waiting for interaction
• User abandoned form
• Long delays between rendering and submission

Solution:

1. Reset widget programmatically
2. Re-initialize widget
3. Prompt user to interact

Example:

{
  'timeout-callback': () => {
    turnstile.reset(widgetId)
    alert('Please complete the verification')
  }
}

---

120*** - Internal Cloudflare Errors

Error: Internal debugging errors (Cloudflare employees only)

Retry: N/A

Solution: Only encountered by Cloudflare Support during debugging.

---

200010 - Invalid Caching

Error: Some portion of Turnstile was accidentally cached

Retry: No

Cause:

• Browser cached Turnstile resources incorrectly
• CDN/proxy caching api.js script

Solution:

1. Clear browser cache
2. Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
3. Ensure api.js is not proxied or cached

CRITICAL: Never proxy or cache https://challenges.cloudflare.com/turnstile/v0/api.js

---

200100 - Time Problem

Error: Visitor's system clock is incorrect

Retry: No

Cause:

• System time is wrong
• Timezone misconfigured
• Date/time not synchronized

Solution:

1. Set system clock to correct time
2. Enable automatic time synchronization
3. Check timezone settings

---

200500 - Loading Error

Error: iframe under challenges.cloudflare.com could not be loaded

Retry: No

Cause:

• Content Security Policy (CSP) blocking iframe
• Browser security settings blocking 3rd-party iframes
• Network firewall blocking challenges.cloudflare.com

Solution:

1. Add CSP directives:

   <meta http-equiv="Content-Security-Policy" content="
     script-src 'self' https://challenges.cloudflare.com;
     frame-src 'self' https://challenges.cloudflare.com;
     connect-src 'self' https://challenges.cloudflare.com;
   ">
   

2. Reduce browser security preferences
3. Check firewall/network settings

Most Common Cause: CSP blocking. See check-csp.sh script.

---

300*** - Generic Client Execution Error

Error: Unspecified error occurred while visitor solved challenge

Retry: Yes

Cause:

• Browser extension interference
• JavaScript errors on page
• Memory issues
• Network interruption

Solution:

1. Retry automatically
2. On continuous failures → potentially automated visitor
3. Disable browser extensions
4. Try incognito/private mode

Known Issue (2025): Safari 18 + macOS 15 with "Hide IP" enabled causes Error 300010.

Safari Fix: Settings → Privacy → Hide IP address → Off

Source: https://community.cloudflare.com/t/turnstile-is-frequently-generating-300x-errors/700903

---

300030 - Widget Crash

Error: Widget crashed for legitimate users

Retry: Yes

Cause: Unknown - Cloudflare-side issue (2025)

Solution:

1. Implement robust error handling
2. Retry with exponential backoff
3. Provide fallback verification method

Example:

let retryCount = 0
const maxRetries = 3

turnstile.render('#container', {
  sitekey: SITE_KEY,
  'error-callback': (error) => {
    if (error.includes('300030') && retryCount < maxRetries) {
      retryCount++
      setTimeout(() => {
        turnstile.reset(widgetId)
      }, 2000 * retryCount) // Exponential backoff
    } else {
      showFallbackVerification()
    }
  }
})

Source: https://community.cloudflare.com/t/turnstile-is-frequently-generating-300x-errors/700903

---

400020 - Invalid Sitekey (Server)

Error: Sitekey is invalid or does not exist

Retry: No

Cause: Same as 110100/110110 but caught server-side

Solution: Verify sitekey exists and is active

---

400030 - Invalid Size

Error: Provided size option is not valid

Retry: No

Cause: Using invalid size parameter

Valid Options: normal, compact, flexible

Solution:

// ❌ Wrong
{ size: 'large' }

// ✅ Correct
{ size: 'compact' }

---

400040 - Invalid Theme

Error: Provided theme is not valid

Retry: No

Cause: Using invalid theme parameter

Valid Options: light, dark, auto

Solution:

// ❌ Wrong
{ theme: 'custom' }

// ✅ Correct
{ theme: 'dark' }

---

401 - Unauthorized (Expected)

Error: 401 error in browser console during challenge

Retry: N/A

Cause: Turnstile requesting Private Access Token (not supported by all devices/browsers)

Solution: Ignore this error - it's expected behavior

Note: If widget is successfully resolving and generating tokens, no action required.

Source: https://developers.cloudflare.com/turnstile/troubleshooting/client-side-errors/error-codes/

---

600*** - Challenge Execution Failure

Error: Visitor failed to solve Turnstile challenge

Retry: Yes

Cause:

• Suspected bot behavior
• Challenge signals indicate automation
• Failing test sitekey (intentional)

Solution:

1. Retry automatically
2. On continuous failures → likely bot
3. Verify visitor by other means
4. Consider alternative verification

Testing: Test sitekey 2x00000000000000000000AB always fails with this error.

---

600010 - Configuration Error

Error: Widget configuration error

Retry: Depends

Cause:

• Missing hostname in allowlist (most common)
• Hostname was deleted from configuration
• Widget misconfigured

Solution:

1. Check Cloudflare Dashboard → Turnstile → Widget Settings
2. Verify hostname in allowed domains
3. Re-add hostname if missing

Known Issue: Hostnames sometimes disappear from dashboard configuration

Source: https://community.cloudflare.com/t/repeated-cloudflare-turnstile-error-600010/644578

---

Browser-Specific Issues

Brave Browser - Confetti Animation Failure (2025)

Error: Verification fails during success animation

Cause: Brave shields block animation scripts

Solution: Handle success callback before animation completes

Source: https://github.com/brave/brave-browser/issues/45608

---

Troubleshooting Checklist

When encountering errors:

1. Check Error Code Family

   • 100*: Initialization → Reload page
   • 110*: Configuration → Check sitekey, domain allowlist
   • 200*: Client issues → Check cache, CSP, system clock
   • 300*: Execution → Retry, check browser compatibility
   • 400*: Invalid input → Fix configuration
   • 600*: Challenge failure → Check for bot-like behavior

2. Common Fixes

   • Clear browser cache
   • Disable browser extensions
   • Try incognito/private mode
   • Check CSP headers
   • Verify system clock
   • Use test sitekey for development

3. Network/Firewall

   • Ensure challenges.cloudflare.com is accessible
   • Check for VPN/proxy interference
   • Verify no firewall blocking

4. Code Review

   • Server-side validation implemented?
   • Token expiration handled?
   • Error callbacks configured?
   • Using latest api.js from CDN?

---

Last Updated: 2025-10-22 Most Common Errors: 110200 (domain), 200500 (CSP), 300030 (crash), 600010 (config)