Should I upgrade to Cloudflare Workers Compatibility Date Upgrade for Cache Rules now?
Teams running older Workers need change-awareness on the 2025-04-02 compatibility behavior shift where Cache Rules no longer win by default for Fetch API cache settings, so they can decide whether to advance compatibility dates now or hold older semantics.
Blockers
- breaking_change_in: runtime/cloudflare-workers → capability/cache-rules
- requires_version: capability/request-cf-overrides-cache-rules → runtime/cloudflare-workers
- requires_version: capability/cache-api-compat-flags → runtime/cloudflare-workers
- requires_version: capability/cache-api-request-cf-overrides-cache-rules → runtime/cloudflare-workers
- Cache API override behavior requires cache_api_compat_flags to also be enabled
Who this is for
- serverless
- high-scale
- low-ops
Candidates
Advance compatibility_date and adopt Worker-overrides-Cache-Rules behavior
Cloudflare changed Fetch API cache precedence with the `request_cf_overrides_cache_rules` compatibility flag, which is enabled by default for Workers with compatibility dates on or after 2025-04-02. For Cache API, the equivalent override behavior uses `cache_api_request_cf_overrides_cache_rules`, which is enabled by default on or after 2025-05-19, and it also requires `cache_api_compat_flags`, default-enabled on or after 2025-04-19. As of 2026-03-28, Cloudflare documents that Workers script settings then take precedence over Cache Rules and Page Rules. Pricing is not the migration driver: as of 2026-03-28, Workers Free includes 100,000 requests per day, and Workers Paid is $5/month with 10 million included requests and 30 million included CPU milliseconds, so changing compatibility dates is a behavior decision rather than a separate priced feature.
When to choose
Use this when you want Worker code to be the single source of truth for cache behavior and you are actively using `request.cf` cache controls or the Cache API. It is the cleaner choice for low-ops teams that prefer current platform semantics, but you should test any routes where Cache Rules previously enforced bypass behavior.
Tradeoffs
Pros: aligns with current Cloudflare behavior, reduces surprise when reading current docs, and lets Worker cache directives win consistently. Cons: can be a breaking change for routes that relied on Cache Rules to block or shape caching despite Worker code.
Cautions
If you need a staged rollout, remember the behavior can still be turned off with `no_request_cf_overrides_cache_rules` on newer compatibility dates. For Cache API users, enabling only `cache_api_request_cf_overrides_cache_rules` is insufficient unless `cache_api_compat_flags` is also enabled.
Hold older semantics and pin or selectively enable flags
If a Worker keeps a compatibility date earlier than 2025-04-02, Cloudflare documents that Cache Rules continue to beat Fetch API cache settings unless you manually enable the new flag. The same staged approach exists for Cache API, but older Workers must manually enable both `cache_api_request_cf_overrides_cache_rules` and `cache_api_compat_flags`; otherwise Cache Rules remain authoritative. As of 2026-03-28, this is still a supported path for teams avoiding immediate behavior drift. This option is especially relevant when Cache Rules are part of your operational guardrails and you do not want Worker code to silently re-enable caching on paths currently bypassed by policy.
When to choose
Use this when cache correctness and operational safety matter more than aligning quickly with current defaults, especially if multiple teams manage Cache Rules and Worker code separately. It is the safer short-term choice when you need audit time for cache bypass routes, custom TTL logic, or Enterprise cache-key behavior.
Tradeoffs
Pros: preserves existing production behavior and lowers migration risk. Cons: increases long-term maintenance overhead because older compatibility dates require ongoing review of flags and historical behavior.
Cautions
Cloudflare notes that if you upload a Worker through the API without specifying `compatibility_date`, it defaults to 2021-11-02, the oldest compatibility date before flags took effect, which can accidentally preserve very old semantics. Also, current docs mainly describe modern behavior, so older-date deployments require disciplined flag tracking.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Should I upgrade to Cloudflare Workers Compatibility Date Upgrade for Cache Rules now?"