I lost hours debugging a Next.js 16 caching issue that had no error, no warning, and only showed up in production.
The Next.js 16 caching model is genuinely good. But it introduces a class of bugs that are harder to detect than anything in previous versions: bugs that look correct, compile without errors, deploy successfully, and then silently misbehave in production.
These are the most common ones I've seen across real projects. Every one comes from real production incidents.
(Assumes you have cacheComponents: true enabled in next.config.ts.)
This is a follow-up to my previous post where I built a dev-only debugger to surface these issues during development. That tool helps you detect them. This post breaks down the exact failure cases behind those warnings.
Bug 1: 'use cache' on the Wrapper Instead of Inside the Function
// This looks cached. It is not.
export const getProducts = someWrapper(async function() {
'use cache'
cacheLife('hours')
return db.query('SELECT * FROM products')
})
The 'use cache' directive tells the Next.js compiler to treat that function as a cache boundary. When you wrap it, the compiler sees the wrapper as the entry point. The inner function may be cached, but the wrapper becomes the execution boundary, so you still end up running it on every request.
No error. No warning. Just a function running on every request when it should be cached.
Fix:
async function _getProducts() {
'use cache'
cacheLife('hours')
cacheTag('products')
return db.query('SELECT * FROM products')
}
// Wrapper receives the already-cached function
export const getProducts = someWrapper(_getProducts)
The rule is simple: 'use cache' lives inside the data function, never on anything that wraps it.
Bug 2: Deprecated revalidateTag That Compiles and Uses Legacy Behavior
// Next.js 15: correct
// Next.js 16: TypeScript error, silently uses legacy behavior in loose tsconfig
revalidateTag('products')
In Next.js 16, revalidateTag without a second argument is deprecated and produces a TypeScript error. But if your tsconfig is not in strict mode (common in older projects), it compiles cleanly and falls back to legacy invalidation behavior instead of the new SWR-based system.
Pages stop reflecting mutations. No error anywhere.
Fix:
revalidateTag('products', 'max') // SWR, recommended for most content
revalidateTag('products', { expire: 0 }) // Immediate expiry for webhooks/payments
Run npx @next/codemod@canary upgrade latest during your migration, it handles this automatically. But check your tsconfig strictness regardless.
Bug 3: Tag String Mismatch Across Files
// lib/data.ts -- written by developer A
async function getProducts() {
'use cache'
cacheTag('product-list') // Tag is 'product-list'
return db.query('...')
}
// app/actions/products.ts -- written by developer B
export async function createProduct(data: ProductData) {
await db.query('INSERT INTO products ...', [...])
revalidateTag('products', 'max') // Different string, invalidates nothing
}
Two different strings. Zero errors. The product list never refreshes after a new product is created. Users see stale data until cacheLife expires on its own.
Fix:
// lib/tags.ts -- one source of truth
export const tags = {
products: 'product-list',
product: (id: string) => `product-${id}`,
user: (id: string) => `user-${id}`,
} as const
// Both files import from tags
cacheTag(tags.products)
revalidateTag(tags.products, 'max')
Tag typos become TypeScript errors. The string mismatch bug becomes structurally impossible.
Bug 4: Server Action Mutation Where the Acting User Sees Stale Data
'use server'
export async function updateProductPrice(id: string, newPrice: number) {
await db.query('UPDATE products SET price = $1 WHERE id = $2', [newPrice, id])
revalidateTag(`product-${id}`, 'max')
}
revalidateTag with any named profile uses stale-while-revalidate. It marks the cache as stale. The next request still gets the cached version while fresh data loads in the background.
For the admin who just clicked save, that means they navigate to the product page and see the old price. Looks like the save failed. Causes confusion and duplicate mutations.
Fix:
'use server'
import { revalidateTag, updateTag } from 'next/cache'
export async function updateProductPrice(id: string, newPrice: number) {
await db.query('UPDATE products SET price = $1 WHERE id = $2', [newPrice, id])
updateTag(`product-${id}`) // Acting user sees change immediately
revalidateTag(`product-${id}`, 'max') // Everyone else gets SWR
revalidateTag('products', 'max') // Product list also refreshes
}
updateTag expires the cache entry immediately. The next request waits for fresh data. The admin sees their change. Everyone else gets the fast SWR treatment.
Constraint: updateTag only works inside Server Actions. In Route Handlers, use revalidateTag(tag, { expire: 0 }) instead.
Bug 5: updateTag in a Route Handler
// app/api/webhooks/stripe/route.ts
import { updateTag } from 'next/cache'
export async function POST(req: Request) {
const event = await parseStripeWebhook(req)
if (event.type === 'price.updated') {
updateTag('products') // Throws at runtime
}
return new Response('ok', { status: 200 })
}
This compiles. It deploys. On the first real webhook call from Stripe, it throws at runtime. updateTag only works inside Server Actions. Calling it anywhere else throws.
Fix:
import { revalidateTag } from 'next/cache'
export async function POST(req: Request) {
const event = await parseStripeWebhook(req)
if (event.type === 'price.updated') {
revalidateTag('products', { expire: 0 }) // Immediate expiry in Route Handlers
}
return new Response('ok', { status: 200 })
}
Bug 6: Short cacheLife That Silently Affects PPR
async function LiveStockStatus({ productId }: { productId: string }) {
'use cache'
cacheLife('seconds') // Seems right for live stock data
cacheTag(`stock-${productId}`)
return fetchStockLevel(productId)
}
cacheLife('seconds'), revalidate: 0, and expire under 5 minutes are automatically excluded from the PPR static shell. They become dynamic holes that run at request time.
One component with cacheLife('seconds') can push parts of the page out of the static shell and turn them into request-time work. No warning. The page still works. It just becomes fully dynamic without any obvious signal.
Fix, if the data can tolerate a short delay:
cacheLife('minutes') // Now included in the static shell
Fix, if it genuinely needs to be live:
// Parent page
<Suspense fallback={<StockSkeleton />}>
<LiveStockStatus productId={id} /> {/* Streams in after static shell */}
</Suspense>
The second approach is the correct PPR pattern for truly dynamic data. The static shell renders instantly and the live data streams in after.
Bug 7: Runtime API Inside a Cached Scope
async function UserHeader() {
'use cache'
const cookieStore = await cookies() // Throws at build time
const user = await getUser(cookieStore.get('user-id')?.value)
return <div>{user.name}</div>
}
cookies(), headers(), and draftMode() are runtime APIs. They read request-specific data. They cannot live inside a 'use cache' scope because cached output is stored and replayed across requests.
This one at least throws at build time with "Uncached data was accessed outside of Suspense". But the error gives you no component name, no file path, and no useful stack trace. You get to play binary search across your codebase to find it.
Fix:
// Read runtime values OUTSIDE the cached scope
async function UserHeader() {
const cookieStore = await cookies()
const userId = cookieStore.get('user-id')?.value
return <CachedUserProfile userId={userId} />
}
// Pass the VALUE as a serializable prop to the cached component
async function CachedUserProfile({ userId }: { userId?: string }) {
'use cache'
cacheLife('hours')
cacheTag(`user-${userId}`)
if (!userId) return <GuestGreeting />
const user = await getUser(userId)
return <div>{user.name}</div>
}
userId is a string so it becomes part of the cache key automatically. Different users produce different cache entries without any manual key construction.
The Common Thread
None of these have good error messages. Five of the seven compile and deploy without complaint. The other two throw, but either without enough information to find the cause quickly or only after the first real production request.
The pattern across all of them is the same: the new caching model requires explicit correctness. When you get something wrong, it does not always tell you.
If you are in the middle of a Next.js 16 migration and want to catch these during development rather than in production, I ended up building a free dev-only debugger that logs cache misses, dynamic holes, missing tags, and deprecated invalidation calls directly in your terminal. Zero production cost, one .tsx file: Next.js cache debugger.
And if you want these patterns enforced at the type level so the wrong call is a compile error rather than a runtime surprise, the production enforcement layer is Cache Pro Kit.
Have you run into any of these? Or something even stranger? I'm curious what the distribution looks like across different kinds of projects.
Top comments (4)
This is the kind of bug category that scares me more than obvious build errors. Caching issues are painful because everything looks fine locally, the app compiles, and then production starts serving stale data or skipping updates in ways that are hard to trace. The biggest lesson is probably not to treat caching as a default performance boost. It needs clear rules, testing, and visibility, especially in Next.js where one wrong assumption can quietly break the user flow.
Yeah, these are the ones that stick with you because nothing clearly breaks. Everything looks correct until it isn’t.
The point about not treating caching as a default performance boost really stands out. In Next.js 16 it’s opt-in, but a lot of issues come from assumptions carried over from earlier versions. That mismatch is where things start behaving in unexpected ways.
Visibility and clear rules around caching make a huge difference here.
Just wondering - did you ever hear about RedwoodSDK?
rwsdk.com/
It's a "competitor" to Next.js and TanStack Start - interesting and elegant concepts, but the big "catch" is that it's pretty tightly tied to CloudFlare ...
Other drawback might be that it's currently very "niche", with a small community - I honestly think they should start marketing it better (or they're just going to get themselves acquired by CloudFlare, which might in fact be the "real" underlying reason why they tied their framework so closely to CF, lol) ...
On the other hand there's of course TanStack Start, which also advertises itself as "less hidden magic" compared to Next.js ... I think both frameworks (RedwoodSDK and TanStack Start) pride themselves in being "easier to understand and debug" than Next.js.
(and all three support RSCs)
I haven't used RedwoodSDK in production yet, but the Cloudflare lock-in does feel like a real tradeoff for most teams.
TanStack Start is interesting too. The "less hidden magic" direction is appealing, especially if you've spent time debugging things that aren't obvious in Next.js.
It's actually interesting that Next.js 16 is moving in a similar direction with more explicit caching. The challenge is just the transition period where the old mental model no longer applies, and things can break in ways that aren't immediately visible.
That's really where most of the issues I mentioned in the post come from.
Curious if you've tried either of them in production?