In a Cloudflare Worker proxying an origin, what do fetch()'s cf options cacheTtl, cacheTtlByStatus, cacheEverything and cacheKey change?
answer
- per-subrequest overrides of the zone cache
- force a lifetime or keep origin's
- status ranges, negative means skip
- custom keys are Enterprise
- edge only, not the browser
basics
~20 sThey change how the edge caches that one subrequest: cacheTtl forces a lifetime whatever the origin says, cacheTtlByStatus sets one per status range, cacheEverything caches any file type but keeps origin lifetimes, and cacheKey (Enterprise only) replaces the cache key.
solid answer
~40 sA Worker's `fetch()` reads through the zone cache, and the `cf` object overrides how that one subrequest is cached. `cacheTtl: 600` forces a ten-minute edge lifetime regardless of the origin's headers, like Edge Cache TTL plus Cache Everything. `cacheTtlByStatus` sets lifetimes per status range, a negative value meaning do not cache, and it does not imply `cacheEverything`. `cacheEverything: true` makes HTML or JSON eligible but still respects the origin's lifetime. `cacheKey` replaces the key and is Enterprise only. These apply to `GET` and `HEAD`, shape the edge only (I rewrite `Cache-Control` for browsers), and since April 2025 override Cache Rules when `request_cf_overrides_cache_rules` is on, which is the default from compatibility date 2025-04-02. Misspelled keys are silently ignored.
code
javascript · 17 linesexport default {
async fetch(request) {
const url = new URL(request.url);
url.hostname = "origin.example.com";
const originResponse = await fetch(new Request(url, request), {
cf: {
cacheEverything: true,
cacheTtlByStatus: { "200-299": 600, "404": 30, "500-599": -1 },
},
});
const response = new Response(originResponse.body, originResponse);
response.headers.set("Cache-Control", "public, max-age=60");
return response;
},
};go deeper
Know that a Worker can change how its fetch() subrequest is cached through the cf object, and that cacheTtl forces an edge lifetime.
Explain the difference between cacheTtl, cacheTtlByStatus and cacheEverything, why they affect the edge but not the browser, and that cacheKey is Enterprise only.
Catch the production traps: silently ignored misspellings, a forced TTL on per-user responses, purging the visitor URL instead of the subrequest URL, and a Cache Rule winning on an old compatibility date.
Decide when per-request cf overrides in code are preferable to zone Cache Rules a wider team can see and change, and who owns the resulting caching policy.
## Where these options act When a Worker calls `fetch()`, the subrequest reads through Cloudflare's cache before it reaches the origin. By default it follows the zone's settings: default cached file extensions, the origin's `Cache-Control`, and any Cache Rules. The `cf` object on the request (`RequestInitCfProperties`) lets the Worker change that behaviour **for this one subrequest**. The response is cached under the subrequest's URL, not the visitor's, and the subrequest goes through **Tiered Cache** when the zone has it enabled. These overrides apply to requests within your own zone or to hosts not on Cloudflare. A request to **another Cloudflare customer's zone** is cached the way that zone decides. ## The four options | Option | What it changes | Origin headers | |---|---|---| | `cacheTtl: 600` | forces caching for 600 seconds, like an Edge Cache TTL plus Cache Everything | ignored for the edge lifetime | | `cacheTtlByStatus` | a TTL per status code or range, for example `{ "200-299": 600, "500-599": -1 }`; a negative value means do not cache | overridden for matching statuses | | `cacheEverything: true` | makes any file type eligible, HTML and JSON included | **respected** for the lifetime | | `cacheKey: "..."` | the key the response is stored and looked up under | not involved | Details that matter: - `cacheTtl`, `cacheTtlByStatus` and `cacheEverything` apply to **`GET` and `HEAD`** only. - `cacheTtl` must be zero or positive; `0` means the entry expires at once. - `cacheTtlByStatus` accepts any integer, and it does **not** turn on `cacheEverything` by itself, so pair the two for HTML or JSON. - `cacheKey` is **Enterprise only**. An asset stored under a custom key set by a Worker cannot be purged by URL; purge by tag, hostname, prefix or everything instead. - `cacheTtl` cannot be combined with the `cache: "no-store"` request option, and `cf.cacheControl` cannot be combined with either of them; the runtime throws on both mixes. ## Caching an origin for ten minutes whatever it says 1. Point the subrequest at the origin and keep the visitor's method and headers (`new Request(url, request)`). 2. Use `cacheTtlByStatus` so success lives 600 seconds while server errors are not cached, or `cacheTtl: 600` when one lifetime for every response is acceptable. 3. Add `cacheEverything: true` if the content type is not on the default cached list. 4. Set the **browser** lifetime separately: the `cf` options shape the edge cache only, so rewrite `Cache-Control` on the response the Worker returns. 5. Make sure the response is the **same for every visitor**. A forced TTL caches regardless of the origin's headers, so a per-user page cached this way can be served to the next visitor. ## How the options meet Cache Rules Since April 2025 a Worker's `cf` cache settings **take precedence over Cache Rules**, and Cache Rules over Page Rules. Two conditions apply: - The compatibility flag `request_cf_overrides_cache_rules` must be on. Compatibility dates from `2025-04-02` turn it on by default; an older date needs the flag listed, or the Cache Rule silently wins. - A Cache Rule meant to apply to a Worker's traffic must match the **subrequest's** URL and headers, not the visitor's. ## Traps - **Misspelled keys are silently ignored.** `cf: { cacheTTL: 600 }` does nothing and raises no error, so review the spelling and confirm the effect with `cf-cache-status` on a deployed route. - **Purging the wrong URL.** The entry belongs to the subrequest URL, so purge that URL, in the zone that owns it. - **Local runs prove little.** `wrangler dev` does not reproduce the edge cache in front of subrequests, so a passing local test says nothing about edge lifetimes. ## Choosing between them - Reach for **`cacheTtlByStatus`** when the origin's errors must never be stored or should be kept only briefly. - Reach for **`cacheTtl`** when one lifetime for every response is acceptable and simplicity matters more. - Reach for **`cacheEverything` alone** when the origin already sends sensible `Cache-Control` and the only problem is that the file type is not cached by default. - Reach for **`cacheKey`** only on Enterprise, and only when several URLs truly return the same content. Used carefully, the `cf` options give a proxy Worker per-request control over edge caching with no extra rules, while keeping Tiered Cache and zone purges working for it.
- After a Worker cached an origin page with cacheTtl, which URL do you purge to remove it?The subrequest's URL, because that is what the cache stored. If a Worker on `example.com/hello` fetches `origin.example.net/hello`, purging `example.com/hello` does nothing. If the fetched host is proxied in another zone you own, purge it from that zone. An entry stored under a custom `cacheKey` cannot be purged by URL at all; use purge by tag, hostname, prefix or everything.
- A Worker with compatibility date 2024-12-01 sets cacheEverything on fetch(), but a Cache Rule bypasses cache for that path. What happens, and what fixes it?The Cache Rule wins and the response is not cached, because `request_cf_overrides_cache_rules` is on by default only from compatibility date 2025-04-02. Either move the compatibility date forward, after checking what else the newer date turns on, or list `request_cf_overrides_cache_rules` in `compatibility_flags`. With it on, the Worker's `cf` settings take precedence over Cache Rules.
- cacheEverything: true ignores the origin's Cache-Control and caches for a fixed time
- cacheTtl on fetch() also sets how long the visitor's browser keeps the response
- A misspelled cf key such as cacheTTL makes fetch() throw an error
- cacheKey custom keys are available on every plan
- A Cache Rule bypass always beats a Worker's cf settings, whatever the compatibility date
- cacheTtl is safe on per-user pages because the origin's Cache-Control still protects them
Assumes the platform as of 2026-10-10: since April 2025 a Worker's fetch() cf cache settings override Cache Rules when request_cf_overrides_cache_rules is on, the default from compatibility date 2025-04-02.