1# Gotchas & Troubleshooting
2 
3## Common Errors
4 
5### "Schema Validation 2.0 not working after migration"
6 
7**Cause:** Classic rules still active, conflicting with new system
8**Solution:**
91. Delete ALL Classic schema validation rules
102. Clear Cloudflare cache (wait 5 min)
113. Re-upload schema via new Schema Validation 2.0 interface
124. Verify in Security > Events
135. Check action is set (Log/Block)
14 
15### "Schema validation blocking valid requests"
16 
17**Cause:** Schema too restrictive, missing fields, or incorrect types
18**Solution:** 
191. Check Firewall Events for violation details
202. Review schema in Settings
213. Test schema in Swagger Editor
224. Use Log mode to validate before blocking
235. Update schema with correct specifications
246. Ensure Schema Validation 2.0 (not Classic)
25 
26### "JWT validation failing"
27 
28**Cause:** JWKS mismatch with IdP, expired token, wrong header/cookie name, or clock skew
29**Solution:** 
301. Verify JWKS matches IdP configuration
312. Check token `exp` claim is valid
323. Confirm header/cookie name matches config
334. Test token at jwt.io
345. Account for clock skew (±5 min tolerance)
356. Use modern syntax: `is_jwt_valid(http.request.jwt.payload["{config_id}"][0])`
36 
37### "BOLA detection false positives"
38 
39**Cause:** Legitimate sequential access patterns, bulk operations, or sensitivity too high
40**Solution:**
411. Review BOLA events in Security > Events
422. Lower sensitivity threshold (High → Medium → Low)
433. Exclude legitimate bulk operations from detection
444. Ensure session identifiers uniquely identify users
455. Verify minimum traffic requirements met (1000+ req/day)
46 
47### "Risk labels not appearing in firewall rules"
48 
49**Cause:** Feature not enabled, insufficient traffic, or missing session identifiers
50**Solution:**
511. Verify Schema Validation 2.0 enabled
522. Enable BOLA Detection in schema settings
533. Configure session identifiers (required for BOLA)
544. Wait 24-48h for ML model training
555. Check minimum traffic thresholds met
56 
57### "Endpoint discovery not finding APIs"
58 
59**Cause:** Insufficient traffic (<500 reqs/10d), non-2xx responses, Worker direct requests, or incorrect session ID config
60**Solution:** Ensure 500+ requests in 10 days, 2xx responses from edge (not Workers direct), configure session IDs correctly. ML updates daily.
61 
62### "Sequence detection false positives"
63 
64**Cause:** Lookback window issues, non-unique session IDs, or model sensitivity
65**Solution:** 
661. Review lookback settings (10 reqs to managed endpoints, 10min window)
672. Ensure session ID uniqueness per user (not shared tokens)
683. Adjust positive/negative model balance
694. Exclude legitimate workflows from detection
70 
71### "GraphQL protection blocking valid queries"
72 
73**Cause:** Query depth/size limits too restrictive, complex but legitimate queries
74**Solution:**
751. Review blocked query patterns in Security > Events
762. Increase max_depth (default: 10) if needed
773. Increase max_size (default: 100KB) for complex queries
784. Whitelist specific query signatures
795. Use Log mode to tune before blocking
80 
81### "Token invalid"
82 
83**Cause:** Configuration error, JWKS mismatch, or expired token
84**Solution:** Verify config matches IdP, update JWKS, check token expiration
85 
86### "Schema violation"
87 
88**Cause:** Missing required fields, wrong data types, or spec mismatch
89**Solution:** Review schema against actual requests, ensure all required fields present, validate types match spec
90 
91### "Fallthrough"
92 
93**Cause:** Unknown endpoint or pattern mismatch
94**Solution:** Update schema with all endpoints, check path pattern matching
95 
96### "mTLS failed"
97 
98**Cause:** Certificate untrusted/expired or wrong CA
99**Solution:** Verify cert chain, check expiration, confirm correct CA uploaded
100 
101## Limits (2026)
102 
103| Resource/Limit | Value | Notes |
104|----------------|-------|-------|
105| OpenAPI version | v3.0.x only | No external refs, must be valid |
106| Schema operations | 10K (Enterprise) | Contact for higher limits |
107| JWT validation sources | Headers/cookies only | No query params/body |
108| Endpoint discovery | 500+ reqs/10d | Minimum for ML model |
109| Path normalization | Automatic | `/profile/238` → `/profile/{var1}` |
110| Schema parameters | No `content` field | No object param validation |
111| BOLA detection | 1000+ reqs/day/endpoint | Per-endpoint minimum |
112| Session ID uniqueness | Required | BOLA/Sequence need unique IDs |
113| GraphQL max depth | 1-50 | Default: 10 |
114| GraphQL max size | 1KB-1MB | Default: 100KB |
115| JWT claim nesting | 10 levels max | Use dot notation |
116| mTLS CA certificates | 5 custom max | CF-managed unlimited |
117| Schema upload size | 5MB max | Compressed OpenAPI spec |
118| Volumetric abuse baseline | 7 days training | Initial ML period |
119| Auth Posture refresh | Daily | Updated nightly |
120 
121## See Also
122 
123- [configuration.md](configuration.md) - Setup guides to avoid common issues
124- [patterns.md](patterns.md) - Best practices and progressive rollout
125- [API Shield Docs](https://developers.cloudflare.com/api-shield/)
126