DEV Community

Mustafa ERBAY
Mustafa ERBAY

Posted on • Originally published at mustafaerbay.com.tr

Cloudflare HTML Cache Stuck at 1.1%: Recovery with Nginx map

Cloudflare dashboard was showing a 1.1% cache rate

I picked up the habit this week of checking the performance dashboard regularly. I opened the stats for the mustafaerbay.com.tr Cloudflare zone. Total Requests 4.1k, Unique Visitors 1.16k. Nice, things are happening. Then the Percent Cached row:

Percent Cached: 1.11%
Enter fullscreen mode Exit fullscreen mode

One point one one percent. So 4.05k of those 4.1k requests are hitting the origin (my VPS) every single time. Cloudflare is caching almost nothing.

If the number were wrong I wouldn't care, but it's real. It costs me a few seconds of lag and chews up my VPS RAM. I need to find the cause.

First hypothesis: Cloudflare misconfigured

Maybe I had no cache rule. The dashboard said Caching → Configuration → "Caching Level: Standard". Standard means "cache according to defaults." By default HTML isn't cached. Hmm. But the cause isn't "Caching Level" — there has to be something more fundamental.

I checked what headers the origin was returning:

$ curl -sI https://mustafaerbay.com.tr/blog/technology/some-post/ | grep -iE "cache|expires|content-type|cf-cache"
content-type: text/html; charset=utf-8
cache-control: public, max-age=0
last-modified: Tue, 28 Apr 2026 10:38:17 GMT
cf-cache-status: DYNAMIC
Enter fullscreen mode Exit fullscreen mode

There it is. cache-control: public, max-age=0.

When Cloudflare sees this header it thinks "even the browser was told not to cache this, so neither will I" → DYNAMIC. Edge cache 0%. Origin is doing all the work.

Let me look at the hashed assets:

$ curl -sI https://mustafaerbay.com.tr/_astro/ClientRouter...js | grep cache
cache-control: public, max-age=31536000, immutable
cf-cache-status: HIT
Enter fullscreen mode Exit fullscreen mode

The JS files are perfect — 1-year immutable, Cloudflare HIT. So Astro adds the immutable header for hashed assets. It only puts max-age=0 on HTML — most likely a defensive default for SSR routes.

The Astro Node adapter is the culprit

The Astro Node adapter takes a "every response is fresh" stance for SSR routes. But most of my pages are prerendered static HTML. Only /api/* and a couple of dynamic pages are SSR. The rest are static files.

The right fix: manually override the cache header for HTML. Patching the Astro Node adapter response directly is messy. A cleaner option: override at the nginx layer.

Content-type-based override with the nginx map directive

This pattern is very powerful in nginx:

map $upstream_http_content_type $mb_cache_control {
    default                  $upstream_http_cache_control;
    "~*^text/html"           "public, max-age=300, s-maxage=3600, stale-while-revalidate=86400";
    "~*^application/xml"     "public, max-age=900, s-maxage=3600";
    "~*^application/rss\+xml" "public, max-age=900, s-maxage=3600";
}

server {
    # ... ssl, server_name vs ...

    location / {
        proxy_pass http://127.0.0.1:3040;
        # ...

        # Override Cache-Control for HTML/feeds; passthrough for assets and /api/*.
        proxy_hide_header Cache-Control;
        add_header        Cache-Control $mb_cache_control always;
    }
}
Enter fullscreen mode Exit fullscreen mode

The logic:

  1. Catches the upstream (Astro Node) response
  2. Inspects the Content-Type header
  3. If it's text/html → s-maxage=3600 (CDN caches for 1 hour)
  4. If it's application/xml → 15 min
  5. Everything else (JS, CSS, image, JSON) → passes through the upstream's own header

proxy_hide_header strips the upstream's Cache-Control. Then add_header puts in the value I mapped. Traffic flow:

Browser → Cloudflare (reads s-maxage, caches 1 hour) → nginx (override) → Astro
Enter fullscreen mode Exit fullscreen mode

A trap: add_header always

I first set this up without the always flag. The Cache-Control header didn't show up on 4xx and 5xx responses. /api/views returns 404 with cache-control: no-store (Astro upstream sets this), but nginx hid it, and its own map doesn't fire for 404 → empty.

always fixes it:

add_header Cache-Control $mb_cache_control always;
Enter fullscreen mode Exit fullscreen mode

Now the map kicks in for every status code. application/json (API) → upstream value passthrough → no-store is returned. text/html (404 page) → max-age=300 → client caches for 5 minutes. That's also fine since 404s don't change much.

Verification

$ curl -sI https://mustafaerbay.com.tr/blog/technology/some-post/ | grep cache
content-type: text/html; charset=utf-8
cache-control: public, max-age=300, s-maxage=3600, stale-while-revalidate=86400
cf-cache-status: HIT
Enter fullscreen mode Exit fullscreen mode

Three parameters:

  • max-age=300 — browser caches for 5 min (F5 to see fresh content)
  • s-maxage=3600 — Cloudflare caches for 1 hour (CDN)
  • stale-while-revalidate=86400 — if the origin is slow, serve stale and refresh in the background

After deploying this, I gave the Cloudflare dashboard 24 hours:

Percent Cached: 47.3%
Enter fullscreen mode Exit fullscreen mode

1.1% → 47.3%. 47x. Origin requests are less than half what they were. My VPS RAM gets to breathe, page load times drop in half, and visitors outside Turkey get fast responses straight from the Cloudflare edge.

ℹ️ Why 47 instead of 50+?

The first request for an article is always a MISS (it has to be put into
cache). Because the trend feed keeps refreshing, a portion is always a MISS.
The /api/* category is always DYNAMIC, always going to the origin. So 47%
in practice means 80%+ HTML hit rate — and those are the requests that
matter most for the user.

A broader lesson

Configuring cache starts with not trusting defaults. The Astro Node adapter sets max-age=0 on the assumption that "any page might be SSR." That's a defensive default and understandable. But my site is 95% prerendered, something Astro doesn't know. Overriding it and saying "I know this page won't change for an hour" is my responsibility.

Second lesson — performance measurement is done with eyes on metrics, not on vibes. Not watching the Percent Cached stat would have left me in the "the site looks fast" world. Looking at the dashboard, seeing the number, asking "what's that 1% about" — that reflex is the starting point of performance optimization.

I'll check the same dashboard tomorrow. I'll see whether 47 climbs higher or hits an asymptote around there. If I need to dig into which sections aren't being cached, I'll look at the top 10 MISS paths. But for now: 47x improvement. A good day.

Top comments (0)