Next.js Dynamic Server Usage Error: Route opted into dynamic rendering

What causes this error

Next.js App Router statically renders routes by default at build time. When Next.js encounters a call to cookies(), headers(), searchParams, or useSearchParams() during static generation, it throws a DynamicServerError because these APIs require an incoming HTTP request — they have no meaningful value at build time. The framework detects this conflict between the route's rendering strategy (static) and the API's requirements (dynamic) and halts the build. In Next.js 14, searchParams in page props was synchronous; in Next.js 15, it became an async Promise that must be awaited, which introduced additional confusion around this error.

How to fix it

1. 01

   step 1

   Identify which dynamic API triggered the error

   The error message tells you which function caused the issue. Look for cookies(), headers(), searchParams access, or useSearchParams() in the route file and any Server Components it imports. The stack trace points to the exact file and line.

   # The build error looks like:
   # Error: Route /dashboard couldn't be rendered statically because it used `cookies`.
   # or: Dynamic server usage: Page couldn't be rendered statically because it used `headers`.

   Copy
2. 02

   step 2

   Decide: does this route need to be static or dynamic?

   If the route shows personalized content (user dashboards, authenticated pages), it should be dynamic — add the route segment config. If the route is mostly static but needs one small dynamic value (like a theme cookie), consider restructuring so the dynamic part lives in a Client Component instead.

3. 03

   step 3

   Option A: Make the route dynamic with segment config

   Add export const dynamic = 'force-dynamic' at the top level of your page or layout file. This tells Next.js to skip static generation for this route and render it on every request.

   // app/profile/page.tsx
   export const dynamic = 'force-dynamic';
   
   import { headers } from 'next/headers';
   
   export default async function Profile() {
     const headerList = await headers();
     const userAgent = headerList.get('user-agent');
     return <div>UA: {userAgent}</div>;
   }

   Copy
4. 04

   step 4

   Option B: Move dynamic logic to a Client Component

   If you want the page shell to remain static, extract the dynamic part into a Client Component that reads cookies or search params on the client side. This preserves static generation for the rest of the page.

   // app/page.tsx — stays static
   import { ThemeSwitcher } from './theme-switcher';
   
   export default function Home() {
     return (
       <div>
         <h1>Welcome</h1>
         <ThemeSwitcher /> {/* reads cookie client-side */}
       </div>
     );
   }
   
   // app/theme-switcher.tsx
   'use client';
   import { useEffect, useState } from 'react';
   
   export function ThemeSwitcher() {
     const [theme, setTheme] = useState('light');
     useEffect(() => {
       const saved = document.cookie
         .split('; ')
         .find(c => c.startsWith('theme='));
       if (saved) setTheme(saved.split('=')[1]);
     }, []);
     return <button>Current: {theme}</button>;
   }

   Copy
5. 05

   step 5

   Handle searchParams correctly in Next.js 15

   In Next.js 15, searchParams is a Promise. If you access it synchronously, you get this error. Await it in the page component, or use useSearchParams() in a Client Component wrapped in Suspense.

   // Next.js 15 — searchParams is async
   export default async function SearchPage({
     searchParams,
   }: {
     searchParams: Promise<{ q?: string }>;
   }) {
     const { q } = await searchParams;
     return <div>Results for: {q}</div>;
   }

   Copy

How to verify the fix

• npm run build completes without DynamicServerError.
• The route renders correctly in production (npm run start) with dynamic data populated.
• Static routes still generate HTML files in .next/server/app/ — only the intended routes are dynamic.

When you’d actually want this

In Next.js 15, cookies() and headers() also became async and must be awaited. Calling them without await triggers a different but related error. If you see 'cookies is not a function' after upgrading to Next.js 15, you need to add await before the call.