Skip to content

secondsky/claude-skills / plugins/cloudflare-turnstile/skills/cloudflare-turnstile

cloudflare-turnstile

Verified

This skill should be used when the user asks to "add turnstile", "implement bot protection", "validate turnstile token", "fix turnstile error", "setup captcha alternative", or encounters error codes 100*/300*/600*, CSP errors, or token validation failures. Provides CAPTCHA-alternative protection for Cloudflare Workers, React, Next.js, and Hono.

references/error-codes.md

View on GitHub
# 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**:
```typescript
// ❌ 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**:
```typescript
// ❌ 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**:
```typescript
{
  '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**:
   ```html
   <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**:
```typescript
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**:
```typescript
// ❌ 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**:
```typescript
// ❌ 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)
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall