Diagnose stale private data, cache modes and revalidation

Understand the likely causes

• Likely causes include mixing Cache Components and traditional guidance, missing audience dimensions, stale source fills after invalidation, unassigned tags, wrong revalidation semantics or old-principal pending results. A URL-only shared key can be unsafe for personalized output. Identify the exact mode and representation rather than assuming one universal Next cache.

Record mode, build, audience and source revision

Preserve the exact configuration, package/build identity, route, principal scope and safe source revision. Determine whether cacheComponents is disabled or explicitly enabled with its versioned companion options. Then name the layer: render memoization, fetch data, route output, shared cache handler or browser state. A helper may return source-cached data even when its HTTP handler is uncached. A build-produced page can reuse output even when a simplistic rule calls fetch uncached by default. Keep raw credentials and private payloads out of diagnostics; identity and revision metadata should be sufficient to frame a synthetic reproduction.

Follow the committed write to every affected representation

Confirm the authoritative change before inspecting invalidation. A title can affect a card, filtered membership, sort order, metadata and a client’s displayed result. Verify that the producer assigned the exact tag the writer invalidates. revalidateTag with a stale profile and updateTag in a Server Action have different freshness behavior; revalidatePath targets paths, while router.refresh requests new route output without universally purging persistent data. A Route Handler’s invalidation can take effect on a later visit. Choose the contract required by the current user rather than changing every API until the screen happens to look fresh.

Separate present storage from usable current data

The local predicate requires a matching tenant and a deadline strictly in the future. It rejects a present record at expiry and rejects another tenant before expiry. It does not model any Next cache algorithm or storage engine. Its purpose is to prevent physical presence from being mistaken for valid authority or freshness. A real permission-sensitive value may also need revocation and source revision checks. An older source request can still repopulate stale data after invalidation, so use explicit interleaving fixtures and the domain’s required version/generation protocol rather than claiming a short lifetime removes the race.

function usable(entry,tenant,now) {return entry.tenant===tenant && now < entry.deadline;}
const entry={tenant:"lab-a",deadline:1000};
console.assert(usable(entry,"lab-a",999));
console.assert(!usable(entry,"lab-a",1000));
console.assert(!usable(entry,"lab-b",999));

Repair audience and lifecycle before increasing reuse

Remove private output from an inappropriate shared representation or include required approved identity dimensions under the actual cache contract. Retire old-account client state and discard incompatible pending responses during identity change. Bound refill concurrency and source deadlines so a cache outage does not create uncontrolled fallback work. Do not cache source failure as legitimate absence. This guide runs the local predicate only, not Next rendering, invalidation or hosting. Verify the narrow repair through authorized build/request/browser tests using safe principals, including the late-fill race and current-user read after write.

Keep it from recurring

• Document mode, cache ownership, lifetime units and tag/path vocabulary with each data contract. Keep shared key construction and writer dependency maps reviewed. Retain private-data isolation and stale-fill fixtures, and never use cache presence as the sole authority for a revoked permission.