Next.js cacheComponents: 'used uncached or runtime data' build error
Cache Components makes the build refuse to guess where the static shell ends. Stream it, cache it with use cache, or declare the route blocking.

Introduction & Quick Summary
Symptom. With Cache Components enabled, next build stops on a route that worked in development:
Error: Route "/products/[id]": Next.js encountered uncached or runtime data during prerendering.
`fetch(...)`, `cookies()`, `headers()`, `params`, `searchParams`, or `connection()`
accessed outside of `<Suspense>` prevents the route from being prerendered.
Ways to fix this:
- [stream] Provide a placeholder with `<Suspense fallback={...}>` around the data access
- [cache] For uncached data (`fetch`, database calls): cache the access with `"use cache"`
- [block] Set `export const instant = false` to allow a blocking routeCause. cacheComponents: true changes what a build means. Next.js now prerenders a static shell for every route and refuses to guess which parts are request-time. Any read of cookies(), headers(), params, searchParams, connection(), or an uncached database call outside a <Suspense> boundary leaves nothing to prerender, so the build fails instead of shipping a slow page.
Fix. Pick one of the three answers per data access: stream it, cache it, or admit the route is blocking.
// app/products/[id]/page.tsx
import { Suspense } from "react";
import { ProductDetail } from "./product-detail";
export default async function Page({ params }: PageProps<"/products/[id]">) {
const { id } = await params; // request-time read, must be inside Suspense or blocking
return (
<Suspense fallback={<p>Loading product…</p>}>
<ProductDetail id={id} />
</Suspense>
);
}// the expensive, stable part is a cache function instead of a request-time read
import { cacheLife, cacheTag } from "next/cache";
export async function getProduct(id: string) {
"use cache";
cacheLife("hours");
cacheTag(`product:${id}`);
return db.product.findUnique({ where: { id } });
}Core Mechanics, Signatures & Reproducible Setup
Cache Components is the completion of the partial prerendering idea: a route is split into a static shell and dynamic holes. The shell is what a CDN can serve without touching your database; the holes stream in per request. For that split to be valid, the compiler has to know where the boundary is, and the only syntax that expresses it is <Suspense> plus explicit caching.
Reproduce it in a fresh app instead of guessing:
npx create-next-app@latest cc-lab --ts --app
cd cc-lab
# next.config.tsimport type { NextConfig } from "next";
const nextConfig: NextConfig = { cacheComponents: true };
export default nextConfig;// app/page.tsx — fails the build
export default async function Page() {
const theme = (await cookies()).get("theme")?.value ?? "light";
return <main data-theme={theme}>hello</main>;
}Adding a Suspense boundary around the part that reads the cookie is enough to make the shell prerenderable again:
import { Suspense } from "react";
import { cookies } from "next/headers";
async function Themed() {
const theme = (await cookies()).get("theme")?.value ?? "light";
return <div data-theme={theme}>hello</div>;
}
export default function Page() {
return (
<Suspense fallback={<div>hello</div>}>
<Themed />
</Suspense>
);
}Two supporting rules come with it. revalidateTag now takes a cache profile as a second argument, and the single-argument form is a type error:
import { revalidateTag } from "next/cache";
// after a mutation
revalidateTag(`product:${id}`, "max");And a route that genuinely cannot stream declares itself blocking rather than fighting the model:
export const instant = false;Key Comparison Table
Which of the three answers fits which access:
| Data access | Streams with Suspense | Works under "use cache" | Blocking route |
|---|---|---|---|
cookies() / headers() | yes | no | yes |
params / searchParams | yes | no | yes |
fetch with cache: "force-cache" | yes | yes | yes |
| Database read via ORM | yes | yes | yes |
connection() | yes | no | yes |
| Current user session lookup | yes | no | yes |
| Cache profile | Revalidate window | Typical use |
|---|---|---|
seconds | about 1 second | near-real-time dashboards |
minutes | about 1 minute | feeds, comment counts |
hours | about 1 hour | catalog pages |
days | about 1 day | marketing and docs |
weeks | about 1 week | rarely changing reference data |
max | effectively indefinite until tagged | static configuration |
Practical Edge Cases, Error Fixes & Deep Dive Code Examples
1. The error names the route, not the line
The message reports the route because the offending read can be several components deep. Search the segment for request-time APIs before you restructure anything:
grep -rn "cookies()\|headers()\|searchParams\|connection()" app/productsA read inside a helper called by a Server Component is still outside <Suspense> unless a boundary sits between the two. Wrapping the page's outermost element in <Suspense> fixes the build and also removes the stream, so wrap the smallest part that needs the request-time value.
2. "use cache" cannot wrap request-time values
A cache function is shared across users, so it cannot read a cookie. The common wrong fix is to cache the whole page and lose personalization:
async function getCart() {
"use cache"; // user-specific data must not be cached this way
const userId = (await cookies()).get("uid")?.value;
return db.cart.findMany({ where: { userId } });
}Split it: read the cookie outside, cache the expensive query by its argument.
async function getCart(userId: string) {
"use cache";
cacheTag(`cart:${userId}`);
return db.cart.findMany({ where: { userId } });
}The cacheTag is what makes invalidation possible, and the tag should include the id so two users do not evict each other.
3. instant = false is a decision, not a workaround
A blocking route is prerendered per request, which means no static shell and no CDN hit. That is correct for an authenticated checkout or a payment callback, and wrong for anything else. Reach for it when the route's first byte always depends on the session, and leave a comment saying so, because the next engineer will otherwise "optimize" it back into a build failure.
// app/account/page.tsx
export const instant = false; // session-dependent, never cached4. Route handlers and metadata images
Route handlers that read request are dynamic by nature; under Cache Components they need to opt in rather than being silently dynamic:
// app/api/report/route.ts
export const instant = false;
export async function GET(request: Request) {
const url = new URL(request.url);
return Response.json({ q: url.searchParams.get("q") });
}The same applies to opengraph-image.tsx and icon.tsx, whose params are now promises. Awaiting them inside the image function is fine; reading them in a helper that runs before the boundary is not.
5. Client components and the CSR bailout
useSearchParams() in a Client Component still fails a prerender with the older bailout message unless it sits under <Suspense>. Under Cache Components the two failures are easy to confuse, so read the first line: missing-suspense-with-csr-bailout is the client-side one, and it is fixed in the component tree, not with instant = false:
// app/search/page.tsx
import { Suspense } from "react";
import { Filters } from "./filters";
export default function Page() {
return (
<Suspense fallback={null}>
<Filters />
</Suspense>
);
}6. Invalidation after a Server Action
A mutation should invalidate with the same tag the read used, and the profile argument decides how long the regenerated entry lives:
"use server";
import { revalidateTag } from "next/cache";
export async function updatePrice(id: string, price: number) {
await db.product.update({ where: { id }, data: { price } });
revalidateTag(`product:${id}`, "max");
}Calling revalidateTag with one argument compiles under JavaScript and fails type checking under TypeScript, which is how many teams discover the change only after a deploy. Test the JSON payload your action returns with the JSON formatter before blaming the cache.
Common Compilation/Runtime Mistakes & Version Gotchas
- Enabling
cacheComponentson an app full ofcookies()reads. Expect one build error per route; budget a day, not an hour. - Wrapping the whole page in
<Suspense>. The build passes and every page becomes a blank shell with a spinner, which is worse for SEO than the blocking route. - Caching personalized data with
"use cache". It compiles and serves one user's data to everyone. Tag per user or do not cache. - Forgetting the second argument to
revalidateTag. Type error in TypeScript, silent no-op expectations in JavaScript. - Assuming
export const dynamicstill controls anything. Route segment config for caching is replaced byinstantand the cache boundaries. - Reading
paramsin a layout without awaiting. Layouts are pages for this rule; the promise must be awaited before use. - Blaming Node. Cache Components needs Node.js 20.9 or later and Turbopack, which Next.js 16 uses by default; an old CI image fails before your code does.
Check which build a route ended up in with the status code reference when a deploy serves a cached shell where you expected a 200 per user.
Reference: Cache Components and revalidateTag in the Next.js documentation.
Official references
primary documentationThe Next.js documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit Next.js work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Next.js guides
All Next.js guidesVercel 504: FUNCTION_INVOCATION_TIMEOUT
A serverless invocation has a wall-clock budget. Measure it, stream or defer the work, and raise maxDuration only where it is earned.
Next.js: useSearchParams() Should Be Wrapped in a Suspense Boundary
A static prerender has no query string, so Next needs a Suspense boundary. Where the boundary belongs, why force-dynamic is different, and how to keep search pages indexable.
Next.js 16 DynamicServerError: cookies(), headers() and fetchCache
Request-time APIs make a route dynamic, and Next 16 replaced the segment configs with Suspense boundaries and use cache. What to delete and what to wrap.
Next.js Server Actions: Swallowed Redirects and Body Limits
redirect() throws, so a try/catch swallows the navigation; the action body parser has a 1 MB limit; and useActionState cannot hold an Error. Fixes for all three.
More in Next.js
All Next.js guidesThe guides filed next to this one in Next.js, in library order.