1# Cache Reserve Gotchas
2 
3## Common Errors
4 
5### "Assets Not Being Cached in Cache Reserve"
6 
7**Cause:** Asset is not cacheable, TTL < 10 hours, Content-Length header missing, or blocking headers present (Set-Cookie, Vary: *)  
8**Solution:** Ensure minimum TTL of 10+ hours (`Cache-Control: public, max-age=36000`), add Content-Length header, remove Set-Cookie header, and set `Vary: Accept-Encoding` (not *)
9 
10### "Range Requests Not Working" (Video Seeking Fails)
11 
12**Cause:** Cache Reserve does **NOT** support range requests (HTTP 206 Partial Content)  
13**Solution:** Range requests bypass Cache Reserve entirely. For video streaming with seeking:
14- Use edge cache only (shorter TTLs)
15- Consider R2 with direct access for range-heavy workloads
16- Accept that seekable content won't benefit from Cache Reserve persistence
17 
18### "Origin Bandwidth Higher Than Expected"
19 
20**Cause:** Cache Reserve fetches **uncompressed** content from origin, even though it serves compressed to visitors  
21**Solution:** 
22- If origin charges by bandwidth, factor in uncompressed transfer costs
23- Cache Reserve compresses for visitors automatically (saves visitor bandwidth)
24- Compare: origin egress savings vs higher uncompressed fetch costs
25 
26### "Cloudflare Images Not Caching with Cache Reserve"
27 
28**Cause:** Cloudflare Images with `Vary: Accept` header (format negotiation) is incompatible with Cache Reserve  
29**Solution:** 
30- Cache Reserve silently skips images with Vary for format negotiation
31- Original images (non-transformed) may still be eligible
32- Use Cloudflare Images variants or edge cache for transformed images
33 
34### "High Class A Operations Costs"
35 
36**Cause:** Frequent cache misses, short TTLs, or frequent revalidation  
37**Solution:** Increase TTL for stable content (24+ hours), enable Tiered Cache to reduce direct Cache Reserve misses, or use stale-while-revalidate
38 
39### "Purge Not Working as Expected"
40 
41**Cause:** Purge by tag only triggers revalidation but doesn't remove from Cache Reserve storage  
42**Solution:** Use purge by URL for immediate removal, or disable Cache Reserve then clear all data for complete removal
43 
44### "O2O (Orange-to-Orange) Assets Not Caching"
45 
46**Cause:** Orange-to-Orange (proxied zone requesting another proxied zone on Cloudflare) bypasses Cache Reserve  
47**Solution:** 
48- **What is O2O**: Zone A (proxied) → Zone B (proxied), both on Cloudflare
49- **Detection**: Check `cf-cache-status` for `BYPASS` and review request path
50- **Workaround**: Use R2 or direct origin access instead of O2O proxy chains
51 
52### "Cache Reserve must be OFF before clearing data"
53 
54**Cause:** Attempting to clear Cache Reserve data while it's still enabled  
55**Solution:** Disable Cache Reserve first, wait briefly for propagation (5s), then clear data (can take up to 24 hours)
56 
57## Limits
58 
59| Limit | Value | Notes |
60|-------|-------|-------|
61| Minimum TTL | 10 hours (36000 seconds) | Assets with shorter TTL not eligible |
62| Default retention | 30 days (2592000 seconds) | Configurable |
63| Maximum file size | Same as R2 limits | No practical limit |
64| Purge/clear time | Up to 24 hours | Complete propagation time |
65| Plan requirement | Paid Cache Reserve or Smart Shield | Not available on free plans |
66| Content-Length header | Required | Must be present for eligibility |
67| Set-Cookie header | Blocks caching | Must not be present (or use private directive) |
68| Vary header | Cannot be * | Can use Vary: Accept-Encoding |
69| Image transformations | Variants not eligible | Original images only |
70| Range requests | NOT supported | HTTP 206 bypasses Cache Reserve |
71| Compression | Fetches uncompressed | Serves compressed to visitors |
72| Worker control | Zone-level only | Cannot control per-request |
73| O2O requests | Bypassed | Orange-to-Orange not eligible |
74 
75## Additional Resources
76 
77- **Official Docs**: https://developers.cloudflare.com/cache/advanced-configuration/cache-reserve/
78- **API Reference**: https://developers.cloudflare.com/api/resources/cache/subresources/cache_reserve/
79- **Cache Rules**: https://developers.cloudflare.com/cache/how-to/cache-rules/
80- **Workers Cache API**: https://developers.cloudflare.com/workers/runtime-apis/cache/
81- **R2 Documentation**: https://developers.cloudflare.com/r2/
82- **Smart Shield**: https://developers.cloudflare.com/smart-shield/
83- **Tiered Cache**: https://developers.cloudflare.com/cache/how-to/tiered-cache/
84 
85## Troubleshooting Flowchart
86 
87Asset not caching in Cache Reserve?
88 
89```
901. Is Cache Reserve enabled for zone?
91   → No: Enable via Dashboard or API
92   → Yes: Continue to step 2
93 
942. Is Tiered Cache enabled?
95   → No: Enable Tiered Cache (required!)
96   → Yes: Continue to step 3
97 
983. Does asset have TTL ≥ 10 hours?
99   → No: Increase via Cache Rules (edge_ttl override)
100   → Yes: Continue to step 4
101 
1024. Is Content-Length header present?
103   → No: Fix origin to include Content-Length
104   → Yes: Continue to step 5
105 
1065. Is Set-Cookie header present?
107   → Yes: Remove Set-Cookie or scope appropriately
108   → No: Continue to step 6
109 
1106. Is Vary header set to *?
111   → Yes: Change to specific value (e.g., Accept-Encoding)
112   → No: Continue to step 7
113 
1147. Is this a range request?
115   → Yes: Range requests bypass Cache Reserve (not supported)
116   → No: Continue to step 8
117 
1188. Is this an O2O (Orange-to-Orange) request?
119   → Yes: O2O bypasses Cache Reserve
120   → No: Continue to step 9
121 
1229. Check Logpush CacheReserveUsed field
123   → Filter logs to see if assets ever hit Cache Reserve
124   → Verify cf-cache-status header (should be HIT after first request)
125```
126 
127## See Also
128 
129- [README](./README.md) - Overview and core concepts
130- [Configuration](./configuration.md) - Setup and Cache Rules
131- [API Reference](./api.md) - Purging and monitoring
132- [Patterns](./patterns.md) - Best practices and optimization
133