Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 ยท CDN and Caching

How Cloudflare CDN Caching Works: Hits, Misses and Defaults

Understand what Cloudflare caches by default, what the cf-cache-status values mean (HIT, MISS, EXPIRED, BYPASS, DYNAMIC) and how to inspect and debug caching.

A content delivery network (CDN) keeps copies of your files in many cities. When the next visitor asks for the same file, the nearby edge answers instantly and your server does no work. Cloudflare turns this on for every proxied hostname, but its defaults are cautious: it caches what is obviously static and leaves the rest alone. Knowing the defaults, and how to see what actually happened, is the foundation of everything else in this chapter.

What gets cached by default

Cloudflare decides by file extension, not by content type. By default it caches static files such as images (.jpg, .png, .webp, .svg, .gif), styles and scripts (.css, .js), fonts (.woff2), media (.mp4, .mp3) and documents (.pdf, .zip). It does not cache HTML or JSON by default, because those are usually dynamic: a page for a logged-in user must never be shown to somebody else.

That caution is deliberate. If you want to cache HTML, for instance a fully static blog, you opt in with a cache rule that makes the response eligible for cache. When you do, you take responsibility for making sure the page does not contain personal data.

There is also a size ceiling for a single cached file (hundreds of megabytes on lower plans), and only GET (and HEAD) responses are stored.

The life of a request

flowchart TB
  R["Request arrives at edge"] --> E{"Eligible for cache?"}
  E -- "no" --> D["Forward to origin, status DYNAMIC or BYPASS"]
  E -- "yes" --> L{"Fresh copy in this data center?"}
  L -- "yes" --> H["Serve it: HIT"]
  L -- "no" --> O["Fetch from origin"]
  O --> S{"Cacheable response?"}
  S -- "yes" --> St["Store, then serve: MISS"]
  S -- "no" --> N["Serve without storing"]

Each data center has its own cache. A MISS in Frankfurt does not fill the cache in Tokyo.

Because every data center caches independently, the first visitor in each city gets a MISS. That is why tiered caching exists: it lets the lower-tier data centers ask a bigger upper tier before bothering your origin.

Reading cf-cache-status

Every response through the proxy carries a cf-cache-status header. Learn these values by heart; they explain nearly every caching question.

Value Meaning
HIT Served from this edge's cache
MISS Cacheable, but not in cache; fetched from origin (and now stored)
EXPIRED Was cached but its lifetime ended; fetched again from origin
REVALIDATED Expired, but the origin confirmed the copy is still good (a 304)
STALE An old copy was served, for example while the origin is down
UPDATING A stale copy is served while a fresh one is being fetched
BYPASS The origin told Cloudflare not to cache (such as no-store) or a rule bypassed the cache
DYNAMIC Not eligible for cache by default (HTML, JSON and so on), so always from origin
NONE or UNKNOWN The request never reached the cache layer (blocked, redirect rule, Worker response)

Check it from the command line. Run the command twice and compare:

Terminal
curl -sI https://example.com/logo.png | grep -i -E "cf-cache-status|age|cache-control"

The second response usually shows cf-cache-status: HIT and an age header, the number of seconds the copy has been sitting in the cache.

JS Stand-in: a cache that reports cf-cache-status

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Why a file is not cached: a checklist

When you expect a HIT and see DYNAMIC or BYPASS, check in this order:

  1. Extension. HTML, JSON and extensionless URLs are not cached by default. Add a cache rule if you want them cached.
  2. Cache-Control from the origin. private, no-store, no-cache or max-age=0 stop caching (unless a rule overrides origin headers).
  3. Cookies. A Set-Cookie on the response is a common reason an asset is skipped; static files should not set cookies.
  4. Request method. POST and other write methods are never cached.
  5. Rules. A cache rule, a Page Rule or a Worker may bypass the cache for that path.
  6. Authorization or query strings that create a unique cache key per visitor (next lessons).

Remember that each data center has its own copy, so a MISS on your first test from a new location is normal.

Browser cache versus edge cache

Two caches exist, and mixing them up causes confusing debugging.

  • The edge cache is Cloudflare's. You control it with s-maxage, Edge Cache TTL and purges.
  • The browser cache is the visitor's. You control it with max-age, Browser Cache TTL and file names that change when the file changes.

Even after you purge the edge, a visitor's browser may keep an old copy until its own max-age ends. For assets that must update, give them a new file name (app.3f2a9c.js) so that no cache anywhere needs invalidating.

JS Stand-in: why versioned file names beat purging

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Benefits you should expect

A well-cached site shows a high cache hit ratio in Caching > Configuration or Analytics: the share of requests served without the origin. Static-heavy sites often reach 90% or more of requests and a large part of bandwidth saved. Lower origin load, lower hosting bills and faster pages follow directly.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Does Cloudflare cache HTML pages by default?

    HTML and JSON are treated as dynamic by default; you opt in with cache rules.
  2. 2. What does cf-cache-status: DYNAMIC mean?

    DYNAMIC means Cloudflare treated the response as not cacheable by default.
  3. 3. A file is cached in Frankfurt. Is it automatically cached in Tokyo?

    Every data center fills its own cache on first request unless tiered caching is used.
  4. 4. Which header shows how long a cached copy has been stored?

    The standard Age header reports the copy's age in seconds.
  5. 5. Best way to make browsers fetch a new JavaScript file after a deploy?

    Fingerprinted file names avoid every cache layer, including browsers.

Summary

  • Cloudflare caches static file extensions by default; HTML and JSON are dynamic unless a rule says otherwise.
  • cf-cache-status tells you what happened: HIT, MISS, EXPIRED, REVALIDATED, STALE, BYPASS, DYNAMIC.
  • Each data center has its own cache; the browser has another one.
  • When a file is not cached, check extension, origin headers, cookies, method and rules.

Next: Cache-Control and TTLs