nextjs - 💡(How to fix) Fix ERR_HTTP_HEADERS_SENT and __next_metadata_boundary__ hydration mismatch when mixing "use cache" with draftMode()/cookies() in same page component [1 comments, 2 participants]

Link to the code that reproduces this issue

(minimal reproduction inline below — a standalone repro repo can be created if needed)

To Reproduce

1. Create a Next.js 16 app with cacheComponents: true
2. Create a page that:
   • Calls a "use cache" function first (e.g. to fetch data from a database)
   • Then accesses a dynamic request API (draftMode(), cookies(), or searchParams) in the same component body
3. Deploy to Vercel (or run next build && next start)
4. Access the page — it renders correctly (HTTP 200), but server logs show errors

Minimal reproduction

next.config.ts

const nextConfig = {
  cacheComponents: true,
  cacheLife: {
    custom: {
      stale: 300,
      revalidate: 3600,
      expire: 86400,
    },
  },
};
export default nextConfig;

app/posts/[slug]/page.tsx

import { draftMode } from "next/headers";
import { connection } from "next/server";
import { cacheTag, cacheLife } from "next/cache";
import { notFound } from "next/navigation";

// "use cache" function — fetches data within a cache boundary
async function cachedPostData(slug: string) {
  "use cache";
  cacheTag("posts", `post:${slug}`);
  cacheLife("custom");

  // Simulate a database fetch (e.g., Payload CMS, Prisma, Drizzle)
  const res = await fetch(`https://jsonplaceholder.typicode.com/posts/1`, {
    cache: "no-store",
  });
  return res.json();
}

// generateMetadata uses connection() because it calls an async library
// that internally uses crypto.randomBytes() (e.g., Effect-TS, Prisma)
export async function generateMetadata({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  await connection();
  const { slug } = await params;
  // Fetch metadata separately (not cached)
  const res = await fetch(`https://jsonplaceholder.typicode.com/posts/1`);
  const post = await res.json();
  return {
    title: post.title,
    description: post.body?.slice(0, 160),
  };
}

export default async function PostPage({
  params,
  searchParams,
}: {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{ draft?: string }>;
}) {
  const { slug } = await params;

  // Step 1: Fetch cached data FIRST
  const post = await cachedPostData(slug);

  if (!post) return notFound();

  // Step 2: Access dynamic APIs AFTER the cached call
  const resolvedSearchParams = await searchParams;
  const { isEnabled: draftModeEnabled } = await draftMode();
  const isDraft = draftModeEnabled || resolvedSearchParams?.draft === "true";

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
      {isDraft && <p>Draft mode is enabled</p>}
    </article>
  );
}

Current vs. Expected behavior

Current:

• The page renders correctly (HTTP 200), but the server logs contain two recurring errors:

Error A — Metadata boundary mismatch (most frequent):

Error: Expected the resume to render <div> in this slot but instead it rendered <__next_metadata_boundary__>.
The tree doesn't match so React will fallback to client rendering.
  { digest: '2161942505' }

Error B — ERR_HTTP_HEADERS_SENT (intermittent):

Error: Cannot set headers after they are sent to the client
  at g.setHeader (.next/server/chunks/ssr/[root-of-the-server]__*.js)
  { code: 'ERR_HTTP_HEADERS_SENT', digest: '1390897066' }

Expected:

• No server-side errors. The cached portion and the dynamic portion should coexist without hydration mismatches or header conflicts.

Impact

Although pages return HTTP 200, these errors cause:

1. Performance degradation: React falls back to full client rendering, discarding the streamed SSR output
2. Wasted server resources: The server does the full SSR work only for it to be thrown away
3. SEO risk: Search engine crawlers may receive incomplete/inconsistent HTML before client JS executes
4. Log noise: In production, this generates ~20-30 errors/hour on a site with moderate traffic

Observed patterns from production

Key observations:

• Error A happens on both cache: STALE (during revalidation) and cache: HIT (serving from cache)
• Error B happens when the page accesses cookies()/draftMode() after a "use cache" call, particularly on cached or prerendered responses
• The connection() call in generateMetadata is required because the underlying data library (Effect-TS) uses crypto.randomBytes() internally, which is disallowed during prerendering
• Both errors come from source: serverless-middleware or source: serverless — framework-level, not application code

Analysis

The root cause appears to be a conflict in how the streaming/resumption protocol handles the transition from a "use cache" boundary to dynamic request APIs within the same server component:

1. generateMetadata runs with connection() (making it dynamic) and produces metadata
2. The page component calls the "use cache" function, which fills/serves from cache and begins streaming
3. After the cache boundary, the page calls draftMode() or cookies(), which attempts to read/set headers
4. The metadata boundary marker (<__next_metadata_boundary__>) gets injected into the stream at a position that doesn't match what React expects during hydration replay — likely because the cache boundary and the metadata boundary are interleaved in a way that changes the DOM structure

The ERR_HTTP_HEADERS_SENT variant occurs when draftMode()/cookies() tries to set response headers (e.g., Set-Cookie) after the cached response has already started streaming to the client.

Provide environment information

Operating System:
  Platform: linux (Vercel serverless)
  Arch: x64
Binaries:
  Node: 24.x
  pnpm: 9.15.9
Relevant Packages:
  next: 16.2.1
  react: 19.1.2
  react-dom: 19.1.2

Which area(s) are affected?

• create-next-app
• App Router: Components, Layouts, Pages
• App Router: Data Fetching (use cache, cacheLife, cacheTag)
• App Router: Metadata (generateMetadata)
• Turbopack
• Deployment (Vercel, Self-hosted, etc.)

NEXT-xxx

No existing issue found.

Additional context

Workarounds attempted:

• Moving draftMode() before the "use cache" call — this breaks prerendering because draftMode() uses crypto internally
• Wrapping the dynamic section in <Suspense> — does not prevent the header conflict
• Removing connection() from generateMetadata — causes prerender errors due to library internals using crypto.randomBytes()

The recommended pattern from the docs (call "use cache" functions, then access dynamic APIs) is exactly what triggers this bug. The "use cache" docs state:

Cached functions and components cannot directly access runtime APIs like cookies(), headers(), or searchParams. Instead, read these values outside the cached scope and pass them as arguments.

We follow this guidance — dynamic APIs are called outside the "use cache" function — but the combination still produces errors when both exist in the same page component.