tools-only Bot Management Gotchas
Common Errors
"Bot Score = 0"
Cause: Bot Management didn't run (internal Cloudflare request, Worker routing to zone (Orange-to-Orange), or request handled before BM (Redirect Rules, etc.))
Solution: Check request flow and ensure Bot Management runs in request lifecycle
"JavaScript Detections Not Working"
Cause: js_detection.passed always false or undefined due to: CSP headers don't allow /cdn-cgi/challenge-platform/, using on first page visit (needs HTML page first), ad blockers or disabled JS, JSD not enabled in dashboard, or using Block action (must use Managed Challenge)
Solution: Add CSP header Content-Security-Policy: script-src 'self' /cdn-cgi/challenge-platform/; and ensure JSD is enabled with Managed Challenge action
"False Positives (Legitimate Users Blocked)"
Cause: Bot detection incorrectly flagging legitimate users
Solution: Check Bot Analytics for affected IPs/paths, identify detection source (ML, Heuristics, etc.), create exception rule like (cf.bot_management.score lt 30 and http.request.uri.path eq "/problematic-path") with Action: Skip (Bot Management), or allowlist by IP/ASN/country
"False Negatives (Bots Not Caught)"
Cause: Bots bypassing detection
Solution: Lower score threshold (30 → 50), enable JavaScript Detections, add JA3/JA4 fingerprinting rules, or use rate limiting as fallback
"Verified Bot Blocked"
Cause: Search engine bot blocked by WAF Managed Rules (not just Bot Management)
Solution: Create WAF exception for specific rule ID and verify bot via reverse DNS
"Yandex Bot Blocked During IP Update"
Cause: Yandex updates bot IPs; new IPs unrecognized for 48h during propagation
Solution:
- Check Security Events for specific WAF rule ID blocking Yandex
- Create WAF exception:
(http.user_agent contains "YandexBot" and ip.src in {<yandex-ip-range>}) Action: Skip (WAF Managed Ruleset) - Monitor Bot Analytics for 48h
- Remove exception after propagation completes
Issue resolves automatically after 48h. Contact Cloudflare Support if persists.
"JA3/JA4 Missing"
Cause: Non-HTTPS traffic, Worker routing traffic, Orange-to-Orange traffic via Worker, or Bot Management skipped
Solution: JA3/JA4 only available for HTTPS/TLS traffic; check request routing
JA3/JA4 Not User-Unique: Same browser/library version = same fingerprint
- Don't use for user identification
- Use for client profiling only
- Fingerprints change with browser updates
Bot Verification Methods
Cloudflare verifies bots via:
- Reverse DNS (IP validation): Traditional method—bot IP resolves to expected domain
- Web Bot Auth: Modern cryptographic verification—faster propagation
When verifiedBot=true, bot passed at least one method.
Inactive verified bots: IPs removed after 24h of no traffic.
Detection Engine Behavior
| Engine | Score | Timing | Plan | Notes |
|---|---|---|---|---|
| Heuristics | Always 1 | Immediate | All | Known fingerprints—overrides ML |
| ML | 1-99 | Immediate | All | Majority of detections |
| Anomaly Detection | Influences | After baseline | Enterprise | Optional, baseline analysis |
| JavaScript Detections | Pass/fail | After JS | Pro+ | Headless browser detection |
| Cloudflare Service | N/A | N/A | Enterprise | Zero Trust internal source |
Priority: Heuristics > ML—if heuristic matches, score=1 regardless of ML.
Limits
| Limit | Value | Notes |
|---|---|---|
| Bot Score = 0 | Means not computed | Not score = 100 |
| First request JSD data | May not be available | JSD data appears on subsequent requests |
| Score accuracy | Not 100% guaranteed | False positives/negatives possible |
| JSD on first HTML page visit | Not supported | Requires subsequent page load |
| JSD requirements | JavaScript-enabled browser | Won't work with JS disabled or ad blockers |
| JSD ETag stripping | Strips ETags from HTML responses | May affect caching behavior |
| JSD CSP compatibility | Requires specific CSP | Not compatible with some CSP configurations |
| JSD meta CSP tags | Not supported | Must use HTTP headers |
| JSD WebSocket support | Not supported | WebSocket endpoints won't work with JSD |
| JSD mobile app support | Native apps won't pass | Only works in browsers |
| JA3/JA4 traffic type | HTTPS/TLS only | Not available for non-HTTPS traffic |
| JA3/JA4 Worker routing | Missing for Worker-routed traffic | Check request routing |
| JA3/JA4 uniqueness | Not unique per user | Shared by clients with same browser/library |
| JA3/JA4 stability | Can change with updates | Browser/library updates affect fingerprints |
| WAF custom rules (Free) | 5 | Varies by plan |
| WAF custom rules (Pro) | 20 | Varies by plan |
| WAF custom rules (Business) | 100 | Varies by plan |
| WAF custom rules (Enterprise) | 1,000+ | Varies by plan |
| Workers CPU time | Varies by plan | Applies to bot logic |
| Bot Analytics sampling | 1-10% adaptive | High-volume zones sampled more aggressively |
| Bot Analytics history | 30 days max | Historical data retention limit |
| CSP requirements for JSD | Must allow /cdn-cgi/challenge-platform/ |
Required for JSD to function |
Plan Restrictions
| Feature | Free | Pro/Business | Enterprise |
|---|---|---|---|
| Granular scores (1-99) | No | No | Yes |
| JA3/JA4 | No | No | Yes |
| Anomaly Detection | No | No | Yes |
| Corporate Proxy detection | No | No | Yes |
| Verified bot categories | Limited | Limited | Full |
| Custom WAF rules | 5 | 20/100 | 1,000+ |