skip to content

In a Cloudflare Worker proxying an origin, what do fetch()'s cf options cacheTtl, cacheTtlByStatus, cacheEverything and cacheKey change?

level: middleimportance: should knowfreq 38%

answer

  1. per-subrequest overrides of the zone cache
  2. force a lifetime or keep origin's
  3. status ranges, negative means skip
  4. custom keys are Enterprise
  5. edge only, not the browser

basics

~20 s

They 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 s

A 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 lines
javascript
export 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

for a junior

Know that a Worker can change how its fetch() subrequest is cached through the cf object, and that cacheTtl forces an edge lifetime.

for a middle

Explain the difference between cacheTtl, cacheTtlByStatus and cacheEverything, why they affect the edge but not the browser, and that cacheKey is Enterprise only.

for a senior

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.

for a principal

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.