1# Troubleshooting & Gotchas
2 
3## Critical Rules
4 
5### ❌ Skipping Server-Side Validation
6**Problem:** Client-only validation is easily bypassed.
7 
8**Solution:** Always validate on server.
9```javascript
10// CORRECT - Server validates token
11app.post('/submit', async (req, res) => {
12  const token = req.body['cf-turnstile-response'];
13  const validation = await fetch('https://challenges.cloudflare.com/turnstile/v0/siteverify', {
14    method: 'POST',
15    body: JSON.stringify({ secret: SECRET, response: token })
16  }).then(r => r.json());
17  
18  if (!validation.success) return res.status(403).json({ error: 'CAPTCHA failed' });
19});
20```
21 
22### ❌ Exposing Secret Key
23**Problem:** Secret key leaked in client-side code.
24 
25**Solution:** Server-side validation only. Never send secret to client.
26 
27### ❌ Reusing Tokens (Single-Use Rule)
28**Problem:** Tokens are single-use. Revalidation fails with `timeout-or-duplicate`.
29 
30**Solution:** Generate new token for each submission. Reset widget on error.
31```javascript
32if (!response.ok) window.turnstile.reset(widgetId);
33```
34 
35### ❌ Not Handling Token Expiry
36**Problem:** Tokens expire after 5 minutes.
37 
38**Solution:** Handle expiry callback or use auto-refresh.
39```javascript
40window.turnstile.render('#container', {
41  sitekey: 'YOUR_SITE_KEY',
42  'refresh-expired': 'auto', // or 'manual' with expired-callback
43  'expired-callback': () => window.turnstile.reset(widgetId)
44});
45```
46 
47## Common Errors
48 
49| Error | Cause | Solution |
50|-------|-------|----------|
51| **Widget not rendering** | Incorrect sitekey, CSP blocking, file:// protocol | Check sitekey, add CSP for challenges.cloudflare.com, use http:// |
52| **timeout-or-duplicate** | Token expired (>5min) or reused | Generate fresh token, don't cache >5min |
53| **invalid-input-secret** | Wrong secret key | Verify secret from dashboard, check env vars |
54| **missing-input-response** | Token not sent | Check form field name is 'cf-turnstile-response' |
55 
56## Framework Gotchas
57 
58### React: Widget Re-mounting
59**Problem:** Widget re-renders on state change, losing token.
60 
61**Solution:** Control lifecycle with useRef.
62```tsx
63function TurnstileWidget({ onToken }) {
64  const containerRef = useRef(null);
65  const widgetIdRef = useRef(null);
66  
67  useEffect(() => {
68    if (containerRef.current && !widgetIdRef.current) {
69      widgetIdRef.current = window.turnstile.render(containerRef.current, {
70        sitekey: 'YOUR_SITE_KEY',
71        callback: onToken
72      });
73    }
74    return () => {
75      if (widgetIdRef.current) {
76        window.turnstile.remove(widgetIdRef.current);
77        widgetIdRef.current = null;
78      }
79    };
80  }, []);
81  
82  return <div ref={containerRef} />;
83}
84```
85 
86### React StrictMode: Double Render
87**Problem:** Widget renders twice in dev due to StrictMode.
88 
89**Solution:** Use cleanup function.
90```tsx
91useEffect(() => {
92  const widgetId = window.turnstile.render('#container', { sitekey });
93  return () => window.turnstile.remove(widgetId);
94}, []);
95```
96 
97### Next.js: SSR Hydration
98**Problem:** `window.turnstile` undefined during SSR.
99 
100**Solution:** Use `'use client'` or dynamic import with `ssr: false`.
101```tsx
102'use client';
103export default function Turnstile() { /* component */ }
104```
105 
106### SPA: Navigation Without Cleanup
107**Problem:** Navigating leaves orphaned widgets.
108 
109**Solution:** Remove widget in cleanup.
110```javascript
111// Vue
112onBeforeUnmount(() => window.turnstile.remove(widgetId));
113 
114// React
115useEffect(() => () => window.turnstile.remove(widgetId), []);
116```
117 
118## Network & Security
119 
120### CSP Blocking
121**Problem:** Content Security Policy blocks script/iframe.
122 
123**Solution:** Add CSP directives.
124```html
125<meta http-equiv="Content-Security-Policy" 
126      content="script-src 'self' https://challenges.cloudflare.com; 
127               frame-src https://challenges.cloudflare.com;">
128```
129 
130### IP Address Forwarding
131**Problem:** Server receives proxy IP instead of client IP.
132 
133**Solution:** Use correct header.
134```javascript
135// Cloudflare Workers
136const ip = request.headers.get('CF-Connecting-IP');
137 
138// Behind proxy
139const ip = request.headers.get('X-Forwarded-For')?.split(',')[0];
140```
141 
142### CORS (Siteverify)
143**Problem:** CORS error calling siteverify from browser.
144 
145**Solution:** Never call siteverify client-side. Call your backend, backend calls siteverify.
146 
147## Limits & Constraints
148 
149| Limit | Value | Impact |
150|-------|-------|--------|
151| Token validity | 5 minutes | Must regenerate after expiry |
152| Token use | Single-use | Cannot revalidate same token |
153| Widget size | 300x65px (normal), 130x120px (compact) | Plan layout |
154 
155## Debugging
156 
157### Console Logging
158```javascript
159window.turnstile.render('#container', {
160  sitekey: 'YOUR_SITE_KEY',
161  callback: (token) => console.log('✓ Token:', token),
162  'error-callback': (code) => console.error('✗ Error:', code),
163  'expired-callback': () => console.warn('⏱ Expired'),
164  'timeout-callback': () => console.warn('⏱ Timeout')
165});
166```
167 
168### Check Token State
169```javascript
170const token = window.turnstile.getResponse(widgetId);
171console.log('Token:', token || 'NOT READY');
172console.log('Expired:', window.turnstile.isExpired(widgetId));
173```
174 
175### Test Keys (Use First)
176Always develop with test keys before production:
177- Site: `1x00000000000000000000AA`
178- Secret: `1x0000000000000000000000000000000AA`
179 
180### Network Tab
181- Verify `api.js` loads (200 OK)
182- Check siteverify request/response
183- Look for 4xx/5xx errors
184 
185## Misconfigurations
186 
187### Wrong Key Pairing
188**Problem:** Site key from one widget, secret from another.
189 
190**Solution:** Verify site key and secret are from same widget in dashboard.
191 
192### Test Keys in Production
193**Problem:** Using test keys in production.
194 
195**Solution:** Environment-based keys.
196```javascript
197const SITE_KEY = process.env.NODE_ENV === 'production'
198  ? process.env.TURNSTILE_SITE_KEY
199  : '1x00000000000000000000AA';
200```
201 
202### Missing Environment Variables
203**Problem:** Secret undefined on server.
204 
205**Solution:** Check .env and verify loading.
206```bash
207# .env
208TURNSTILE_SECRET=your_secret_here
209 
210# Verify
211console.log('Secret loaded:', !!process.env.TURNSTILE_SECRET);
212```
213 
214## Reference
215 
216- [Turnstile Docs](https://developers.cloudflare.com/turnstile/)
217- [Dashboard](https://dash.cloudflare.com/?to=/:account/turnstile)
218- [Error Codes](https://developers.cloudflare.com/turnstile/troubleshooting/)
219