Supabase Storage Cache Control: REST API Sets no-cache

My own repository told me this was unfixable. A comment I left in ops/make-thumbnails.py on 2026-07-29 said the cache-control header I send at upload time lands in the object's metadata but that the public URL "still serves no-cache", called it a serving-layer problem, and signed off with an instruction to future me: don't try to fix this by changing the upload call. I re-measured it today. The comment was wrong, and the wrong diagnosis hid a sharper problem.

What a REST upload really stores

Supabase's own docs say "The default TTL is typically set to 1 hour, which is generally a reasonable default value." That describes the JavaScript client, where DEFAULT_FILE_OPTIONS carries cacheControl: '3600' and converts it to max-age=3600. Upload straight to the REST endpoint and nobody supplies that default for you. I put the same 20KB WebP through four upload paths and read back metadata.cacheControl:

Upload method	Stored cacheControl
REST, no cache-control header	no-cache
REST, header public, max-age=31536000, immutable	verbatim
REST, header max-age=3600	max-age=3600
multipart form field cacheControl=3600 (SDK style)	max-age=3600

So the documented one-hour default is a client-library default, not a server default. The header and the multipart form field are equivalent — the difference that matters is whether anything gets sent at all. One normalization detail showed up on the way out: send bare max-age=3600 and the response comes back as public, max-age=3600, while the longer string with immutable is preserved character for character.

The origin honors it, on all 31 of ours

The blocking claim in my old comment was that serving ignores the stored value. It does not. I audited every image behind this blog — 31 objects, each one uploaded by the script carrying that comment:

stored cacheControl: 31/31  public, max-age=31536000, immutable
served cache-control: 31/31  public, max-age=31536000, immutable
mismatches: 0

Zero. Those are the URLs the build writes into every page, assembled from the same database that serves as this static site's CMS. The audit also showed 29 of 31 returning cf-cache-status: MISS, including objects created two days earlier, which is its own quiet finding: at the traffic this blog gets — the same order of magnitude that made the Workers KV free-tier write limit my real ceiling — the edge cache is almost always cold, so the header I fought over is doing much less work than I assumed.

Where the no-cache actually came from

The symptom is real, and it appears the moment you write twice to the same path. Create an object with no header, then re-upload it with one:

Step	Stored	Served on the bare public URL
create, no header	no-cache	no-cache
POST x-upsert: true with header	updated to 1 year	no-cache
PUT with header	1 year	no-cache

It is symmetric. Create an object with the one-year header, overwrite it without one, and the stored value drops to no-cache while the URL keeps handing out the one-year header. Metadata and response had come apart, which is exactly what "serving layer problem" felt like. The test that settles it costs one query string:

GET /object/public/blog-images/probe.webp        -> no-cache                            (cf-cache-status: HIT)
GET /object/public/blog-images/probe.webp?v=2    -> public, max-age=31536000, immutable
GET /object/blog-images/probe.webp   (authed)    -> public, max-age=31536000, immutable

Change the cache key and the current value appears instantly. The origin was never wrong; a cached edge response was answering for it. Sending Cache-Control: no-cache on the request does not force revalidation either — the edge keeps serving its copy.

The value you set does not control staleness

Once the edge is the suspect, the useful question changes. Does a short cache-control protect you from serving a stale file? I uploaded image A to a path, fetched it once to warm the edge, overwrote it with a visibly different image C, then polled the bare public URL every ten seconds comparing md5 of the body:

Object's own cache-control	Edge kept serving the old bytes for
no-cache	stale through t=50s, fresh at t=61s
public, max-age=31536000, immutable	stale through t=50s, fresh at t=61s

Identical. An object whose every response reads cache-control: no-cache still served a minute of stale bytes, with cf-cache-status: HIT printed next to no-cache in the same response. cacheControl decides the header text handed to browsers; it has no say in whether the edge caches that response or how long it answers with an old one. The ~60s matches what the Smart CDN docs promise for invalidation: "It can take up to 60 seconds for the CDN cache to be invalidated as the asset metadata has to propagate across all the data-centers around the globe."

Purging works, and the documented curl call does not

The purge API shortens that window. Purging the path at t=20s got fresh bytes at t=26s, against t=61s with no purge. The documented curl example sends only apikey, and that fails:

$ curl -X DELETE ".../storage/v1/cdn/blog-images/probe.webp" -H "apikey: $KEY"
{"statusCode":"400","message":"headers must have required property 'authorization'"}

# add Authorization and it returns
{"message":"success"}

One limit I could not close: the docs gate Smart CDN and purge at "Pro Plan and above", and my .env holds no management API token, so I cannot read this project's plan tier. Purge returning 200 and invalidation landing near 60 seconds is measured behavior here, not a claim about what a free-tier project does.

What I changed

The bug worth fixing was never the header. Every thumbnail here lives at a slug-derived path like automation/<slug>/thumb.webp and carries max-age=31536000, immutable. The edge forgets an old copy in about a minute; a browser that already fetched one will not ask again for a year, and purge explicitly does not touch browser caches. So regenerating cards in place with --force would leave returning readers on the old image indefinitely — and the docs say as much: "If you have assets that undergo frequent updates, it is advisable to upload the new asset to a different path." I replaced the false comment in both upload scripts with that constraint instead.

This is the second thing one upload call got wrong for me. The same three header lines are where I found that Supabase Storage stamps x-robots-tag: none on public files, which had quietly excluded 16 OG images from image search. Both share a shape with the Cloudflare edge rule that 403s Python-urllib: the origin behaved, and something in front of it answered first. storage#18, filed in May 2021, describes a real version of my wrong diagnosis, since the API back then did ignore cache-control and return no-cache; it was fixed. storage#120 collects the problem I actually had, where "even though a new image has been uploaded to the Supabase storage, the CDN still uses the old image". I matched my symptom to a five-year-old closed bug and stopped looking.

The cheap habit that would have caught it: before blaming a serving layer, re-request the same object under a different cache key. If ?v=2 disagrees with the bare URL, the origin is fine and you are arguing with a cache. That check took one line and sat undone for a day, next to a comment telling me not to bother.

Everything above was measured on 2026-07-30 against this blog's own Supabase project and bucket, using the service-role key over the REST endpoints — four upload methods, three serving endpoints, a 31-object audit of the images this site actually ships, and md5-compared polling to time the stale window. Numbers for the stale window come from single runs at 10s and 5s poll intervals, so read "~61s" as one minute and change, not a precise constant. Doc quotes link to Supabase's Smart CDN and purge pages as read today; the plan-tier question is flagged unresolved above rather than guessed. Full notes, including the two repo comments this corrected, are in projects/blog-en/research/supabase-storage-cache-control-rest-api.md.