Fixing next/navigation usePathname Errors in Next.js App Router

Introduction

The usePathname hook from next/navigation is one of the most commonly used hooks in the App Router. It returns the current URL path and is essential for building navigation components, breadcrumbs, and active link highlighting. Despite its simplicity, developers frequently encounter errors when using it incorrectly.

This post covers every error scenario I have encountered with usePathname and provides concrete solutions for each.

Environment

• OS: Windows 11
• Node.js: v20.10.0
• Next.js: 14.0.4
• React: 18.2.0

Problem

The most common errors encountered:

Error: usePathname only works in Client Components. Add "use client" to the top of your file.

Warning: React does not recognize the `pathname` prop on a DOM element.

Hydration Mismatch: Text content did not match.
Server: "/about"
Client: "/"

TypeError: Cannot read properties of null (reading 'useContext')

Analysis

Each error has a specific cause:

1. Server Component usage. usePathname is a React hook, and hooks can only be used in Client Components. Using it in a Server Component produces an immediate error.

2. Hydration mismatch. During server rendering, usePathname returns the server-side path. If the server and client paths differ (e.g., due to middleware rewriting), a hydration mismatch occurs.

3. Missing "use client" directive. The directive must be at the very top of the file, before any imports.

4. Importing from wrong module. Some developers import usePathname from next/router (Pages Router) instead of next/navigation (App Router).

Solution

Fix 1: Always mark the component as a Client Component

// components/Navigation.tsx
'use client' // This MUST be the first line

import { usePathname } from 'next/navigation'

export function Navigation() {
  const pathname = usePathname()

  return (
    
  )
}

Fix 2: Handle hydration mismatch with useEffect

// components/ClientPathname.tsx
'use client'

import { usePathname } from 'next/navigation'
import { useEffect, useState } from 'react'

export function ClientPathname() {
  const pathname = usePathname()
  const [mounted, setMounted] = useState(false)

  useEffect(() => {
    setMounted(true)
  }, [])

  // Return a consistent value during SSR and initial hydration
  if (!mounted) {
    return Loading...
  }

  return Current path: {pathname}
}

Fix 3: Extract pathname-dependent logic into a custom hook

// hooks/useActiveRoute.ts
'use client'

import { usePathname } from 'next/navigation'
import { useMemo } from 'react'

export function useActiveRoute(patterns: string[]) {
  const pathname = usePathname()

  return useMemo(() => {
    return {
      pathname,
      isActive: patterns.some(
        (pattern) => pathname === pattern || pathname.startsWith(pattern + '/')
      ),
      isExact: patterns.includes(pathname),
    }
  }, [pathname, patterns])
}

// components/NavItem.tsx
'use client'

import { useActiveRoute } from '@/hooks/useActiveRoute'
import Link from 'next/link'

interface NavItemProps {
  href: string
  label: string
}

export function NavItem({ href, label }: NavItemProps) {
  const { isActive } = useActiveRoute([href])

  return (
    
      {label}
    
  )
}

Fix 4: Use path-based conditional rendering safely

// components/Breadcrumbs.tsx
'use client'

import { usePathname } from 'next/navigation'
import Link from 'next/link'

export function Breadcrumbs() {
  const pathname = usePathname()

  // Split path into segments, filtering out empty strings
  const segments = pathname.split('/').filter(Boolean)

  // Generate breadcrumb items
  const breadcrumbs = segments.map((segment, index) => {
    const href = '/' + segments.slice(0, index + 1).join('/')
    const label = decodeURIComponent(segment)
      .replace(/-/g, ' ')
      .replace(/\b\w/g, (c) => c.toUpperCase())

    return { href, label }
  })

  if (breadcrumbs.length === 0) return null

  return (
    
  )
}

Fix 5: Prevent wrong import

// WRONG
import { usePathname } from 'next/router'

// CORRECT
import { usePathname } from 'next/navigation'

Lessons Learned

1. usePathname requires "use client". There is no way around this. If you need pathname information in a Server Component, you must extract it from the URL on the server side.

2. Hydration mismatches with usePathname are common when middleware rewrites or redirects modify the path. Always handle the mounted state.

3. Use usePathname with useMemo when computing derived values to prevent unnecessary re-renders.

4. next/navigation is the App Router module. next/router is for Pages Router only. Mixing them causes undefined behavior.

5. Combine usePathname with useSearchParams for complete URL information:

'use client'

import { usePathname, useSearchParams } from 'next/navigation'

export function useCurrentUrl() {
  const pathname = usePathname()
  const searchParams = useSearchParams()

  const queryString = searchParams.toString()
  const fullUrl = queryString ? `${pathname}?${queryString}` : pathname

  return { pathname, searchParams, fullUrl }
}

This blog does not accept any external sponsorships, affiliate marketing, or ad revenue.