router.query is empty or undefined the first time a page renders
router.query is {} on the first render and filled in on the next oneShort answer
On a statically optimized page the router's query is empty while the page is prerendered. Next.js fills it in after hydration and renders again. Read it in an effect that waits for router.isReady. If the file is under app/, there is no query or isReady: use useSearchParams and useParams.
Fix it fast
1Find out which cause you have
Log the router fields on every render, and note whether the file sits under pages/ or under app/. The values on the first and second render tell the causes apart.
const router = useRouter() console.log(router.isReady, router.query, router.asPath)2Match what you see, then jump to its fix
- 1
The first log shows isReady false and query {}. A later log shows isReady true and the real values.The page is statically optimized, so the query is empty at firstFix - 2
useRouter() has no query or isReady, or a shared component breaks on a null routerThe file lives in app/ and uses next/navigationFix - 3
router.query holds a value, for example { slug: 'a' }, but router.query.id is undefinedThe query key does not match the dynamic segment's file nameFix - 4
The page shows a server and client mismatch when router.asPath appears in the markup of a statically optimized pagerouter.asPath is rendered before the router is readyFix
- 1
What does the error look like?
router.query is {} on the first render and filled in on the next onerouter.query.id is undefined in the component body or in the first run of useEffectuseRouter() from next/navigation has no query and no isReadyA component shared with the app directory fails because useRouter from next/compat/router is null
Cause 1 of 4
The page is statically optimized, so the query is empty at first
1Check
A page without getServerSideProps or getInitialProps is prerendered to static HTML, and no query exists in that phase. After hydration Next.js triggers another render with the route parameters. This applies to dynamic routes, URLs that carry a query string, and sites with rewrites. Confirm the page file has no server-side data function.
grep -n "getServerSideProps\|getInitialProps\|getStaticProps" "pages/posts/[id].js"2Fix
Wait for router.isReady inside useEffect before reading the query. The docs say isReady is for effects and not for deciding what to render on the server. If the first render itself needs the value, read it on the server instead: getServerSideProps receives query and params in its context.
import { useEffect, useState } from 'react'
import { useRouter } from 'next/router'
export default function Post() {
const router = useRouter()
const [post, setPost] = useState(null)
useEffect(() => {
if (!router.isReady) return
const { id } = router.query
fetch(`/api/posts/${id}`).then((r) => r.json()).then(setPost)
}, [router.isReady, router.query])
return <p>{post ? post.title : 'Loading...'}</p>
}3Verify
Open the page directly on a URL that carries the value and confirm the request uses the real id, not undefined.
npm run devConfirmed by nextjs.org
Cause 2 of 4
The file lives in app/ and uses next/navigation
1Check
In the App Router the useRouter hook comes from next/navigation. Its pathname and query were removed, isReady was removed as unnecessary, and search and route parameters are separate hooks. Check which router the file belongs to.
grep -rn "next/router\|next/navigation\|next/compat/router" app pages components2Fix
Use useSearchParams for the query string and useParams for dynamic segments, in a Client Component. A component that must work under both pages/ and app/ can use next/compat/router, which returns null when the Pages Router is not mounted, so guard it before reading fields. During prerendering, useSearchParams renders on the client up to the nearest Suspense boundary, so wrap the component that calls it.
// Filters.tsx
'use client'
import { useParams, useSearchParams } from 'next/navigation'
export default function Filters() {
const { id } = useParams<{ id: string }>()
const q = useSearchParams().get('q')
return <p>{id} {q}</p>
}
// page.tsx
// <Suspense fallback={null}><Filters /></Suspense>3Verify
Open the route with a value in the path and a ?q= value and confirm both print.
npm run devConfirmed by nextjs.org
Cause 3 of 4
The query key does not match the dynamic segment's file name
1Check
The name inside the square brackets in the file name is the key. pages/blog/[slug].js turns /blog/a into { slug: 'a' }, and a catch-all like [...slug] gives an array.
console.log(router.query)2Fix
Read the key that matches the file name, or rename the file. For a catch-all segment, expect an array.
// pages/blog/[slug].js
const { slug } = router.query
// pages/shop/[...slug].js: /shop/a/b gives { slug: ['a', 'b'] }3Verify
Log router.query after isReady is true and check the key you read exists.
console.log(router.isReady, router.query)Confirmed by nextjs.org
Cause 4 of 4
router.asPath is rendered before the router is ready
1Check
Statically optimized pages know asPath only on the client, so using it in the rendered output can differ between the server and the browser.
grep -rn "router.asPath" pages components2Fix
Hold the value in state and set it from an effect once isReady is true.
const [path, setPath] = useState('')
useEffect(() => {
if (router.isReady) setPath(router.asPath)
}, [router.isReady, router.asPath])3Verify
Reload the page and confirm the console has no mismatch warning.
npm run devConfirmed by nextjs.org
How do I stop it coming back?
- Treat router.query as incomplete until router.isReady is true on any page without a server-side data function.
- Name dynamic segments after what they hold, and read the same name everywhere the page uses it.
- In the App Router, reach for useParams and useSearchParams from the start and keep next/router out of the app directory.
- When a route needs its value for the first render, load the data on the server rather than waiting in the browser.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
router.push() does nothing or throws in a Next.js app
router.push() runs but the URL or page does not change
In the App Router, import useRouter from next/navigation, call it in a Client Component, and use it in event handlers.
3 causes, each with a fixWeb apps
"invariant expected app router to be mounted" in a Next.js app
Uncaught Error: invariant expected app router to be mounted
This error appears when a component calls useRouter imported from next/router while it renders inside the App Router.
3 causes, each with a fixWeb apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb apps
react-i18next shows the wrong plural form for a count, or prints the key instead of the text
t('item') prints the key item instead of a translated sentence
i18next picks a plural from the count option and looks for keys ending in _one, _other and so on.
4 causes, each with a fixWeb apps
useSession throws because there is no SessionProvider above it
[next-auth]: `useSession` must be wrapped in a <SessionProvider />
useSession reads the session from React Context, and SessionProvider is what creates that context.
3 causes, each with a fix