Next.js build logs 'Dynamic server usage' for a route handler that reads searchParams
Dynamic server usage: Page couldn't be rendered statically because it used `nextUrl.searchParams`Short answer
Next.js tries to build a route handler as static HTML or data. When the handler reads the incoming request, such as nextUrl.searchParams, it cannot be static. Declare the route dynamic with export const dynamic = 'force-dynamic', or upgrade, since GET handlers stopped being cached by default in Next.js 15.
Fix it fast
1Find out which cause you have
Run a production build and note which route the message names. The route table at the end shows whether it is marked static or dynamic.
npx next build2Match what you see, then jump to its fix
- 1
The route is app/**/route.ts, exports GET, and calls request.nextUrl.searchParams or new URL(request.url)A GET route handler on Next.js 14 reads the requestFix - 2
DynamicServerError thrown from code that uses cookies() or headers() inside setTimeout, setInterval or an unawaited promisecookies() or headers() is called outside the request's call stackFix - 3
The file exports dynamic = 'error' or dynamic = 'force-static'The route is forced to be static or to fail on request APIsFix
- 1
What does the error look like?
Dynamic server usage: Page couldn't be rendered statically because it used `nextUrl.searchParams`DynamicServerError
Cause 1 of 3
A GET route handler on Next.js 14 reads the request
1Check
In Next.js 14, GET handlers that return a Response were cached by default, and using the Request object is one of the things that opts out. The build tries static first, sees the request being read, and reports it. Check the Next.js version and the handler.
npx next --version
grep -rn "nextUrl.searchParams" app --include=route.ts --include=route.js2Fix
Say so explicitly: export dynamic = 'force-dynamic' from the route file. On Next.js 15 and later GET handlers are dynamic by default, so upgrading removes the need.
// app/api/search/route.ts
import { type NextRequest } from 'next/server'
export const dynamic = 'force-dynamic'
export function GET(request: NextRequest) {
const query = request.nextUrl.searchParams.get('query')
return Response.json({ query })
}3Verify
Rebuild and check that the route is listed as dynamic, then call it with a query string.
npx next build
npx next start &
curl "http://localhost:3000/api/search?query=hello"Confirmed by nextjs.org
Cause 2 of 3
cookies() or headers() is called outside the request's call stack
1Check
These functions only work while the request that started the render is still on the call stack. Find any call that sits inside a timer callback or a promise you did not await.
grep -rnE "setTimeout|setInterval" app lib | head -202Fix
Call cookies() or headers() first, in the main async function, and pass the value into the timer or promise. Await every promise that reads them.
import { cookies } from 'next/headers'
async function getCookieData() {
const cookieStore = await cookies()
const cookieData = cookieStore.getAll()
return new Promise((resolve) =>
setTimeout(() => resolve(cookieData), 1000)
)
}3Verify
Run the build again; the error should not appear.
npx next buildConfirmed by nextjs.org
Cause 3 of 3
The route is forced to be static or to fail on request APIs
1Check
'error' makes the build fail if the route uses request-time APIs or uncached data. 'force-static' prerenders the route and makes cookies and headers return empty values, so a handler that depends on them gets nothing.
grep -rnE "export const dynamic" app2Fix
If the route must read the request, remove those exports or set dynamic = 'force-dynamic'. If it must stay static, stop reading request data in it and move that logic to a dynamic route.
// before
export const dynamic = 'force-static'
// after
export const dynamic = 'force-dynamic'3Verify
Build again and confirm the route shows as dynamic.
npx next buildConfirmed by nextjs.org
How do I stop it coming back?
- Declare dynamic = 'force-dynamic' on every handler that depends on the request, so the intent is written in the file.
- Read the build's route table after upgrades; the static and dynamic markers tell you how each route is served.
- Call cookies() and headers() at the top of the function, before any timer or promise.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix