Troubleshoot

Troubleshooting Next.js

Diagnostics and fixes for common Next.js issues. Start with the quick diagnostics checklist, then check the categorized error tables.

Quick Diagnostics Checklist

1. Check Next.js version: npx next --version — ensure 14+ for stable App Router
2. Check Node.js version: node -v — 20.9+ required for Next.js 16
3. Clear cache: rm -rf .next && npm run dev
4. Check TypeScript: npx tsc --noEmit — catch type errors early
5. Check console: Both browser console and terminal for error messages
6. Check MCP: If using next-devtools-mcp, call nextjs_call with get_errors

Hydration Errors

The most common Next.js issue. Occurs when server-rendered HTML doesn't match client-rendered output. Since Next.js 16.2, the dev overlay shows a labeled +Client/-Server diff pinpointing the exact mismatching markup.

Common Hydration Causes

// BAD: Different output on server vs client
export default function Clock() {
  return <p>Time: {new Date().toLocaleTimeString()}</p>
}

// GOOD: Use client-only rendering for dynamic values
'use client'
import { useState, useEffect } from 'react'

export default function Clock() {
  const [time, setTime] = useState<string>()
  useEffect(() => {
    setTime(new Date().toLocaleTimeString())
  }, [])
  return <p>Time: {time ?? 'Loading...'}</p>
}

// BAD: Checking window in render
export default function Component() {
  const isDesktop = window.innerWidth > 768  // Fails on server
  return isDesktop ? <Desktop /> : <Mobile />
}

// GOOD: Use CSS media queries or useEffect
'use client'
import { useState, useEffect } from 'react'

export default function Component() {
  const [isDesktop, setIsDesktop] = useState(false)
  useEffect(() => {
    setIsDesktop(window.innerWidth > 768)
  }, [])
  return isDesktop ? <Desktop /> : <Mobile />
}

Locale-Dependent Date Rendering

toLocaleDateString() produces different output on server vs client because locale settings differ. Three approaches, from best to simplest:

Approach 1 — ISO initial render + client upgrade (recommended):

Render a stable ISO string on the server, then upgrade to the user's locale format after hydration. No mismatch, no flash of wrong content for most users:

// components/formatted-date.tsx
'use client'

import { useState, useEffect } from 'react'

export function FormattedDate({ dateString }: { dateString: string }) {
  const [formatted, setFormatted] = useState(() => {
    // Stable initial render — matches server output
    return new Date(dateString).toISOString().split('T')[0]
  })

  useEffect(() => {
    // After hydration, upgrade to user's locale format
    setFormatted(new Date(dateString).toLocaleDateString())
  }, [dateString])

  return <time dateTime={dateString}>{formatted}</time>
}

Use in a Server Component page:

// app/blog/[id]/page.tsx — Server Component
import { FormattedDate } from '@/components/formatted-date'

export default async function BlogPost({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params
  const post = await getPost(id)
  return (
    <article>
      <h1>{post.title}</h1>
      <FormattedDate dateString={post.date} />
      <p>{post.content}</p>
    </article>
  )
}

Approach 2 — Fixed locale (simpler but less flexible):

Pin the locale so server and client produce identical output:

'use client'

export function FormattedDate({ dateString }: { dateString: string }) {
  return (
    <time dateTime={dateString}>
      {new Date(dateString).toLocaleDateString('en-US', {
        year: 'numeric', month: 'long', day: 'numeric',
      })}
    </time>
  )
}

Approach 3 — suppressHydrationWarning (last resort):

<time dateTime={post.date} suppressHydrationWarning>
  {new Date(post.date).toLocaleDateString()}
</time>

Only use suppressHydrationWarning for leaf elements where the mismatch is cosmetic (e.g., date formatting). It does not fix the mismatch — it silences the warning and shows the client output after hydration.

'use client' Errors

Build Errors

Data Fetching Errors

Image Issues (next/image)

Debugging tip: When images appear broken with no error, always check /_next/image requests in the browser Network tab — the HTTP status reveals whether the issue is upstream auth (403), missing config (400), or network (502/504).

Performance Issues

Deployment Issues

For platform-specific deployment issues (Vercel, Dokploy, Netlify, etc.), see the respective deployment plugin (vercel-dev, dokploy-dev). Common cross-platform issues:

Diagnostic Commands

# Check Next.js version
npx next --version

# Generate route types + full type check
npx next typegen && npx tsc --noEmit

# Clean build
rm -rf .next node_modules/.cache && npm run build

# Debug prerender errors
npx next build --debug-prerender

# Check bundle (Turbopack analyzer, 16.1+)
npx next experimental-analyze

# Debug with the Node inspector
npx next dev --inspect

When to Escalate

• Persistent 500 errors: Check server logs, not just browser. Use next-devtools-mcp get_errors tool
• Memory leaks: Profile with --inspect flag and Chrome DevTools
• MCP connection failures: Verify Next.js 16+, dev server running, and next-devtools-mcp in .mcp.json
• Webpack/Turbopack crashes: Turbopack is the default in 16 — reproduce with next dev --webpack / next build --webpack to isolate bundler issues
• Deployment-specific bugs: Test with next build && next start locally before deploying