[BUG] bypassTagCacheOnCacheHit serves stale entries after on-demand revalidateTag

[gaauwe]

Describe the bug

We're running into an issue where a page is still serving old data after revalidation. We're observing the following on a page (/download) whose data is tagged releases:

1. Initial request → served from the regional cache (x-opennext-cache: HIT).
2. We call revalidateTag("releases", { expire: 0 }).
3. Next request → no x-opennext-cache header and x-powered-by: Next.js (so cache interception fell through to NextServer), but x-nextjs-cache: HIT and the old release version is still served. It stays stale on subsequent requests too.

Setting bypassTagCacheOnCacheHit: false makes revalidation work correctly, so it's specifically tied to that option. But since the bypassTagCacheOnCacheHit significantly improves our performance, we prefer to keep that on.

We've met what the docs describe as the requirements for using it on Next 16+ (cache purge configured with Enterprise plan, and only ever using revalidateTag(tag, { expire: 0 }) rather than SWR-style revalidation), which is why we're unsure whether this is a bug or whether we're using regional cache / bypassTagCacheOnCacheHit incorrectly.

I've analyzed the code with an agent, which pointed to the following:

opennextjs-cloudflare/packages/cloudflare/src/api/overrides/incremental-cache/regional-cache.ts

Lines 159 to 168 in 127942d

	const rawEntry = await this.store.get(key, cacheType);
	const { value, lastModified } = rawEntry ?? {};
	if (!value || typeof lastModified !== "number") return null;
	debugCache("RegionalCache", `get ${key} -> put to cache`);
	// Update the locale cache after retrieving from the store.
	getCloudflareContext().ctx.waitUntil(
	this.putToCache({ key, cacheType, entry: { value, lastModified } })
	);

On a regional cache miss this unconditionally re-populates the Cache API from the underlying store (R2). After revalidateTag, the store still holds the previous render (revalidate only marks the tag + purges the regional/CDN copy — it doesn't rewrite the store or regenerate), so this refill re-seeds a stale value. With bypassTagCacheOnCacheHit: true, the next regional hit is returned with shouldBypassTagCache: true, so the tag cache is never re-checked and the stale entry is served as fresh — and since the handler reports a fresh hit, NextServer never regenerates, so the store stays stale until the regional TTL expires. With enableCacheInterception it's near-deterministic: the interceptor's miss re-seeds the cache right before NextServer's own read hits it.

To verify this I created the following patch which resolves it in our local testing:

// PATCH(regional-cache stale refill): only the bypass-trusted Cache API can
// serve a stale entry as "fresh", so don't re-seed it with a value the tag
// cache already considers revalidated. When bypass is off, hits re-check tags
// anyway, so a stale refill is harmless and we skip the extra read.
let isRevalidated = false;
if (this.opts.bypassTagCacheOnCacheHit) {
    try {
        const tags = getTagsFromCacheEntry({ value, lastModified }) ?? [key];
        isRevalidated = await hasBeenRevalidated(key, tags, { value, lastModified });
    }
    catch (e) {
        error("Failed to check revalidation on regional cache miss", e);
    }
}
if (isRevalidated) {
    debugCache("RegionalCache", `get ${key} -> stale, skipping regional refill`);
}
else {
    debugCache("RegionalCache", `get ${key} -> put to cache`);
    // Update the locale cache after retrieving from the store.
    getCloudflareContext().ctx.waitUntil(this.putToCache({ key, cacheType, entry: { value, lastModified } }));
}

Sequence — current behavior (stale served)

sequenceDiagram
    participant C as Client
    participant I as Interceptor
    participant RC as RegionalCache
    participant CA as "Cache API"
    participant R2 as "R2 store"
    participant TC as "Tag cache (D1)"
    participant NS as NextServer

    Note over RC,CA: releases revalidated + regional entry purged
    C->>I: GET /download
    I->>RC: get("/download")
    RC->>CA: match -> MISS
    RC->>R2: get -> STALE value
    RC-->>CA: re-seed (putToCache) STALE
    Note right of CA: POISON - stale re-seeded
    RC-->>I: stale (no bypass flag)
    I->>TC: hasBeenRevalidated -> true
    I-->>NS: fall through (no x-opennext-cache)
    NS->>RC: get("/download")
    RC->>CA: match -> HIT (poisoned stale)
    RC-->>NS: stale + shouldBypassTagCache=true
    Note over NS: tag check skipped -> treated as fresh
    NS-->>C: OLD data, x-nextjs-cache HIT (no regeneration)

Loading

Sequence — with the patch (regenerates fresh)

sequenceDiagram
    participant C as Client
    participant I as Interceptor
    participant RC as RegionalCache
    participant CA as "Cache API"
    participant R2 as "R2 store"
    participant TC as "Tag cache (D1)"
    participant NS as NextServer

    Note over RC,CA: releases revalidated + regional entry purged
    C->>I: GET /download
    I->>RC: get("/download")
    RC->>CA: match -> MISS
    RC->>R2: get -> STALE value
    RC->>TC: hasBeenRevalidated -> true
    Note right of RC: stale -> skip refill (no poison)
    RC-->>I: stale (no bypass flag)
    I->>TC: hasBeenRevalidated -> true
    I-->>NS: fall through
    NS->>RC: get("/download")
    RC->>CA: match -> MISS (still empty)
    RC->>TC: hasBeenRevalidated -> true (skip refill)
    RC-->>NS: stale (no bypass flag)
    Note over NS: handler re-checks tags -> regenerate
    NS->>NS: regenerate /download (fresh)
    NS->>RC: set fresh
    NS-->>C: FRESH data

Loading

Is this indeed a bug in the miss-path refill when bypassTagCacheOnCacheHit is enabled, or are we misconfiguring / misunderstanding how the regional cache works? If it is a bug, I'd be happy to open a PR but I wanted check in about the expected behavior first.

Steps to reproduce

export default defineCloudflareConfig({
  incrementalCache: withRegionalCache(r2IncrementalCache, {
    mode: "long-lived",
    bypassTagCacheOnCacheHit: true,
  }),
  queue: doQueue,
  tagCache: withFilter({ tagCache: d1NextTagCache, filterFn: softTagFilter }),
  enableCacheInterception: true,
  cachePurge: purgeCache({ type: "direct" }),
});

1. Deploy a Next 16 app with the config above (regional cache + bypassTagCacheOnCacheHit: true + enableCacheInterception + cachePurge).
2. Have an ISR/SSG page whose content comes from data tagged releases. Request it so it's cached (x-opennext-cache: HIT).
3. Call revalidateTag("releases", { expire: 0 }).
4. Request the page again → it's served stale (x-nextjs-cache: HIT, old content) and does not regenerate.

Expected behavior

After revalidateTag(tag, { expire: 0 }), the next request to a page using that tag should regenerate and serve fresh content (as it does with bypassTagCacheOnCacheHit: false, and as self-hosted Next / Vercel do).

@opennextjs/cloudflare version

1.19.10

Wrangler version

4.91.0

next info output

Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.5.0: Mon Apr 27 20:41:15 PDT 2026; root:xnu-12377.121.6~2/RELEASE_ARM64_T6041
  Available memory (MB): 36864
  Available CPU cores: 14
Binaries:
  Node: 22.22.2
  npm: 10.9.7
  Yarn: N/A
  pnpm: 9.15.9
Relevant Packages:
  next: 16.2.6 // There is a newer version (16.2.9) available, upgrade recommended!
  eslint-config-next: N/A
  react: 19.2.4
  react-dom: 19.2.4
  typescript: 5.3.3
Next.js Config:
  output: N/A

[conico974]

Ho yeah sorry I forgot to add that in the docs (and to fix it 😉). I'll try to have a fix for it this weekend.
The server and the middleware config needs to be different in this situation, the middleware can have bypassTagCacheOnCacheHit but not the server.
You can separate them like I did here https://github.com/GitbookIO/gitbook/blob/main/packages/gitbook/open-next.config.ts

[gaauwe]

Awesome! Makes sense that the setting should indeed only apply to the middleware

[conico974]

@gaauwe Could you test with #1303 (comment)

[gaauwe]

Whoops accidentally closed the issue.. I'm not sure if I'm still misunderstanding how the regional cache works, but I tested 2 scenarios which both didn't work.

I've used the following test setup:

• We have a page that fetches JSON data that is tagged
• We call revalidateTag(tag, { expire: 0 }) through an API endpoint
• Verify headers before and after revalidation
• Verify page content before and after revalidation

Separate config for server and middleware

Based on the gitbook example I applied a separate config for the server and middleware:

const config = defineCloudflareConfig({
    incrementalCache: withRegionalCache(r2IncrementalCache, {
        mode: "long-lived",
        bypassTagCacheOnCacheHit: false,
    }),
    queue: doQueue,
    tagCache: withFilter({
        tagCache: d1NextTagCache,
        filterFn: softTagFilter,
    }),
    enableCacheInterception: true,
    cachePurge: purgeCache({ type: "direct" }),
})

if (config.middleware?.external) {
    config.middleware.override = {
        ...config.middleware.override,
        incrementalCache: () =>
            withRegionalCache(r2IncrementalCache, {
                mode: "long-lived",
                bypassTagCacheOnCacheHit: true,
            }),
    }
}

The initial page headers contain x-opennext-cache: HIT. After revalidation I don't get the x-opennext-cache header, but I'm still seeing x-nextjs-cache: HIT (and stale content).

The fix in #1303

Installed https://pkg.pr.new/@opennextjs/cloudflare@1303 with the following config:

const config = defineCloudflareConfig({
    incrementalCache: withRegionalCache(r2IncrementalCache, {
        mode: "long-lived",
        bypassTagCacheOnCacheHit: true,
    }),
    queue: doQueue,
    tagCache: withFilter({
        tagCache: d1NextTagCache,
        filterFn: softTagFilter,
    }),
    enableCacheInterception: true,
    cachePurge: purgeCache({ type: "direct" }),
})

The initial page headers contain x-opennext-cache: HIT. After revalidation I kept getting the x-opennext-cache: HIT header. Loading the page from another region did have the updated page content and after waiting a while my own region returned the updated page content after ~10 minutes.

I'd expect that if we revalidate a page with purge cache 'direct', that the next visit to the page should render on demand with the new content? I'm happy to help debug this further, let me know if/how I can help!

[conico974]

The problem clearly seems to be the purge cache. Not sure how you set it up. Try clearing the cache manually (either after your API call to revalidateTag or manually in the cloudflare dashboard)

[gaauwe]

To double check the cache purging I copied internalPurgeCacheByTags into our revalidation endpoint to get the result:

revalidateTag(tag, { expire: 0 })
const result = await internalPurgeCacheByTags([tag])

return Response.json({
    revalidated: result === "purge-success",
    message: result,
    now: Date.now(),
})

Which returns:

{"revalidated":true,"message":"purge-success","now":1783502312591}

But the page still has the x-opennext-cache: HIT response header and is serving stale data. I also tried manually purging the tags through the Cloudflare dashboard but that has the same result.

Since the regional cache purge flow is only fully active on a production domain, we've had to deploy this test twice with similar results:

• Yesterday deployed a version with the PR install -> always contained x-opennext-cache: HIT
• Yesterday deployed a version with the normal install -> no x-opennext-cache: HIT after revalidate
• Today deployed a version with the PR install -> always contained x-opennext-cache: HIT
• Today deployed a version with the normal install -> no x-opennext-cache: HIT after revalidate

This seemed odd to me, so I started investigating with an agent. It suggested to inspect the cache with the following API endpoint:

export async function GET(req: NextRequest) {
    const { getCloudflareContext } = await import("@opennextjs/cloudflare")
    const { cf } = getCloudflareContext()
    const cache = await caches.open("incremental-cache")
    const buildId = process.env.OPEN_NEXT_BUILD_ID ?? "no-build-id"
    const key = `http://cache.local/${buildId}/agent-metrics.cache`
    const hit = await cache.match(key)
    return Response.json({
        colo: cf?.colo,
        key,
        hit: !!hit,
        headers: hit ? Object.fromEntries(hit.headers) : null,
    })
}

Normal install:

{
  "colo": "AMS",
  "key": "http://cache.local/xtIztefcT7y0q8MjNwflS/agent-metrics.cache",
  "hit": true,
  "headers": {
    "age": "0",
    "cache-control": "max-age=1800",
    "cache-tag": "_N_T_/layout,_N_T_/(site)/layout,_N_T_/(site)/agent-metrics/layout,_N_T_/(site)/agent-metrics/page,_N_T_/agent-metrics,agent-metrics",
    "cf-cache-status": "HIT",
    "content-length": "1828391",
    "content-type": "text/plain;charset=UTF-8",
    "date": "Wed, 08 Jul 2026 12:13:45 GMT"
  }
}

PR install:

{
  "colo": "AMS",
  "key": "http://cache.local/9ZGFhjeCDhjZp24xEFOGn/agent-metrics.cache",
  "hit": true,
  "headers": {
    "age": "0",
    "cache-control": "max-age=1800",
    "cache-tag": "/agent-metrics",
    "cf-cache-status": "HIT",
    "content-length": "1828236",
    "content-type": "text/plain;charset=UTF-8",
    "date": "Wed, 08 Jul 2026 12:16:36 GMT"
  }
}

Note that the cache-tag is different

Found it — full root cause, in @opennextjs/aws's getTagsFromValue:

const cacheTags = value.meta?.headers?.["x-next-cache-tags"]?.split(",") ?? [];
delete value.meta?.headers?.["x-next-cache-tags"];   // ← mutates the shared value object!
return cacheTags;

Every consumer that checks tags (the cache interceptor at cacheInterceptor.ts:290, and the server cache handler) strips x-next-cache-tags out of the cached value as a side effect. Now look at the ordering difference:

• 1.20.1: get() schedules putToCache immediately; its getTagsFromCacheEntry(entry) runs within a microtask or two — before the interceptor's getTagsFromValue strips the header. Tags intact → full cache-tag → purgeable. (It's technically a race — the immediate write usually wins.)
• PR Update regional cache management and dependency #1303: the write is deliberately deferred until after the tag-cache verdict — i.e. guaranteed after getTagsFromValue has already deleted the header from the very same value object the pending entry holds a reference to. getTagsFromCacheEntry finds nothing → falls back to [key] → cache-tag: /agent-metrics → unpurgeable, deterministically.

And it's worse than just unpurgeable: the flushed entry is JSON.stringify'd from the mutated object, so the stored copy has no x-next-cache-tags in its meta.headers at all. Future reads of that regional entry yield tags = [], and hasBeenRevalidated short-circuits to false on empty tags — so those entries dodge the tag cache even with bypass disabled. Double poison.

[conico974]

Ho yeah right. I'll make the change.
I'm sorry I don't have much time to test it myself.