Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

router.query is empty or undefined the first time a page renders

Errorrouter.query is {} on the first render and filled in on the next one

Short 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.

  • Applies to Next.js 15, Next.js 16, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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)
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2useRouter() has no query or isReady, or a shared component breaks on a null routerThe file lives in app/ and uses next/navigationFix
    3. 3router.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. 4The 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

What does the error look like?

  • router.query is {} on the first render and filled in on the next one
  • router.query.id is undefined in the component body or in the first run of useEffect
  • useRouter() from next/navigation has no query and no isReady
  • A 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 dev

Confirmed by nextjs.org

Did this fix it?

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 components

2Fix

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 dev

Confirmed by nextjs.org

Did this fix it?

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

Did this fix it?

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 components

2Fix

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 dev

Confirmed by nextjs.org

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.