Fix guide · Netlify

Netlify ignored your max-age. Here’s what it does instead.

Netlify treats a deploy as the invalidation event: every new deploy clears the cache for that context. The trap is the opposite of most hosts — a short Cache-Control on a static asset does not shorten edge caching at all.

Netlify's edge holds static assets for up to a year. A deploy, or a tag purge, is what replaces them.

Not sure this is the layer? Paste your URL and the checker reads the headers for you.

Check my site

How to tell what Netlify did

Netlify sets a Cache-Status header on all responses, in the RFC 9211 format. source

"Netlify Edge"; hitServed from Netlify’s edge cache.

"Netlify Edge"; fwd=missNo response found in the cache, so it went to your site.

"Netlify Edge"; fwd=staleThe cached copy was stale and was revalidated.

"Netlify Edge"; hit; fwd=staleA stale copy was served while it revalidated in the background.

"Netlify Durable"; hit; ttl=…Served from the durable cache, with the remaining lifetime.

Three cache-control headers are read, in this order of precedence: Netlify-CDN-Cache-Control, then CDN-Cache-Control, then Cache-Control. source

What Netlify caches by default

Static assets default to Netlify-CDN-Cache-Control: public, s-maxage=31536000, must-revalidate, so they are treated as fresh for up to a year — and shorter max-age values are ignored. source
Dynamic responses from Functions, Edge Functions and proxies are not cached by default; they get Cache-Control: public, max-age=0, must-revalidate. source

How to clear it

Deploy. All new deploys invalidate the cache for that deploy context by default. On Netlify this is the normal purge. source
By tag. Tag responses with Netlify-Cache-Tag: news,blog (or Cache-Tag), then purge from a function: import { purgeCache } from "@netlify/functions" and await purgeCache({ tags: ["news"] }). Calling purgeCache() with no arguments purges the site. source
By API: POST https://api.netlify.com/api/v1/purge with a personal access token and a body of {"site_slug": "yoursite", "cache_tags": ["news"]}. Each tag or site can only be purged twice every five seconds. source

If it still serves the old file

You set a short max-age and expected it to apply. On static assets it is ignored; use Netlify-CDN-Cache-Control to control the edge, and Cache-Control for the browser. source
Where to set headers: a _headers file (per deploy) or a [[headers]] block in netlify.toml (global for all builds). source source
You opted out of deploy invalidation. Responses marked with Netlify-Cache-ID survive deploys and are registered as cache tags, so they need a tag purge. source

Other fix guides

LiteSpeed Cloudflare Hostinger WordPress Vercel nginx Service workers

Sources

Every step above was written from these pages, read on 14 Sep 2026. Vendors move buttons; if one has moved, the source page will say where.