1570 Gotchas B8081dd6

# Troubleshooting & Gotchas

## Critical Rules

### ❌ Skipping Server-Side Validation

**Problem:** Client-only validation is easily bypassed.

**Solution:** Always validate on server.

```javascript
// CORRECT - Server validates token
app.post('/submit', async (req, res) => {
  const token = req.body['cf-turnstile-response']
  const validation = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
    method: 'POST',
    body: JSON.stringify({ secret: SECRET, response: token }),
  }).then((r) => r.json())

  if (!validation.success) return res.status(403).json({ error: 'CAPTCHA failed' })
})
```

### ❌ Exposing Secret Key

**Problem:** Secret key leaked in client-side code.

**Solution:** Server-side validation only. Never send secret to client.

### ❌ Reusing Tokens (Single-Use Rule)

**Problem:** Tokens are single-use. Revalidation fails with `timeout-or-duplicate`.

**Solution:** Generate new token for each submission. Reset widget on error.

```javascript
if (!response.ok) window.turnstile.reset(widgetId)
```

### ❌ Not Handling Token Expiry

**Problem:** Tokens expire after 5 minutes.

**Solution:** Handle expiry callback or use auto-refresh.

```javascript
window.turnstile.render('#container', {
  sitekey: 'YOUR_SITE_KEY',
  'refresh-expired': 'auto', // or 'manual' with expired-callback
  'expired-callback': () => window.turnstile.reset(widgetId),
})
```

## Common Errors

| Error                      | Cause                                             | Solution                                                          |
| -------------------------- | ------------------------------------------------- | ----------------------------------------------------------------- |
| **Widget not rendering**   | Incorrect sitekey, CSP blocking, file:// protocol | Check sitekey, add CSP for challenges.cloudflare.com, use http:// |
| **timeout-or-duplicate**   | Token expired (>5min) or reused                   | Generate fresh token, don't cache >5min                           |
| **invalid-input-secret**   | Wrong secret key                                  | Verify secret from dashboard, check env vars                      |
| **missing-input-response** | Token not sent                                    | Check form field name is 'cf-turnstile-response'                  |

## Framework Gotchas

### React: Widget Re-mounting

**Problem:** Widget re-renders on state change, losing token.

**Solution:** Control lifecycle with useRef.

```tsx
function TurnstileWidget({ onToken }) {
  const containerRef = useRef(null)
  const widgetIdRef = useRef(null)

  useEffect(() => {
    if (containerRef.current && !widgetIdRef.current) {
      widgetIdRef.current = window.turnstile.render(containerRef.current, {
        sitekey: 'YOUR_SITE_KEY',
        callback: onToken,
      })
    }
    return () => {
      if (widgetIdRef.current) {
        window.turnstile.remove(widgetIdRef.current)
        widgetIdRef.current = null
      }
    }
  }, [])

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

### React StrictMode: Double Render

**Problem:** Widget renders twice in dev due to StrictMode.

**Solution:** Use cleanup function.

```tsx
useEffect(() => {
  const widgetId = window.turnstile.render('#container', { sitekey })
  return () => window.turnstile.remove(widgetId)
}, [])
```

### Next.js: SSR Hydration

**Problem:** `window.turnstile` undefined during SSR.

**Solution:** Use `'use client'` or dynamic import with `ssr: false`.

```tsx
'use client'
export default function Turnstile() {
  /* component */
}
```

### SPA: Navigation Without Cleanup

**Problem:** Navigating leaves orphaned widgets.

**Solution:** Remove widget in cleanup.

```javascript
// Vue
onBeforeUnmount(() => window.turnstile.remove(widgetId))

// React
useEffect(() => () => window.turnstile.remove(widgetId), [])
```

## Network & Security

### CSP Blocking

**Problem:** Content Security Policy blocks script/iframe.

**Solution:** Add CSP directives.

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

### IP Address Forwarding

**Problem:** Server receives proxy IP instead of client IP.

**Solution:** Use correct header.

```javascript
// Cloudflare Workers
const ip = request.headers.get('CF-Connecting-IP')

// Behind proxy
const ip = request.headers.get('X-Forwarded-For')?.split(',')[0]
```

### CORS (Siteverify)

**Problem:** CORS error calling siteverify from browser.

**Solution:** Never call siteverify client-side. Call your backend, backend calls siteverify.

## Limits & Constraints

| Limit          | Value                                  | Impact                       |
| -------------- | -------------------------------------- | ---------------------------- |
| Token validity | 5 minutes                              | Must regenerate after expiry |
| Token use      | Single-use                             | Cannot revalidate same token |
| Widget size    | 300x65px (normal), 130x120px (compact) | Plan layout                  |

## Debugging

### Console Logging

```javascript
window.turnstile.render('#container', {
  sitekey: 'YOUR_SITE_KEY',
  callback: (token) => console.log('✓ Token:', token),
  'error-callback': (code) => console.error('✗ Error:', code),
  'expired-callback': () => console.warn('⏱ Expired'),
  'timeout-callback': () => console.warn('⏱ Timeout'),
})
```

### Check Token State

```javascript
const token = window.turnstile.getResponse(widgetId)
console.log('Token:', token || 'NOT READY')
console.log('Expired:', window.turnstile.isExpired(widgetId))
```

### Test Keys (Use First)

Always develop with test keys before production:

- Site: `1x00000000000000000000AA`
- Secret: `1x0000000000000000000000000000000AA`

### Network Tab

- Verify `api.js` loads (200 OK)
- Check siteverify request/response
- Look for 4xx/5xx errors

## Misconfigurations

### Wrong Key Pairing

**Problem:** Site key from one widget, secret from another.

**Solution:** Verify site key and secret are from same widget in dashboard.

### Test Keys in Production

**Problem:** Using test keys in production.

**Solution:** Environment-based keys.

```javascript
const SITE_KEY = process.env.NODE_ENV === 'production' ? process.env.TURNSTILE_SITE_KEY : '1x00000000000000000000AA'
```

### Missing Environment Variables

**Problem:** Secret undefined on server.

**Solution:** Check .env and verify loading.

```bash
# .env
TURNSTILE_SECRET=your_secret_here

# Verify
console.log('Secret loaded:', !!process.env.TURNSTILE_SECRET);
```

## Reference

- [Turnstile Docs](https://developers.cloudflare.com/turnstile/)
- [Dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)
- [Error Codes](https://developers.cloudflare.com/turnstile/troubleshooting/)