Next.js Common Errors - Complete Next.js Tutorial

🐛 Common Next.js Errors

Every developer encounters errors while building Next.js applications. This guide covers the most common errors you'll face, explains why they happen, and provides clear solutions to fix them quickly and get back to coding.


# Typical error message
Error: Hydration failed because the initial UI 
does not match what was rendered on the server.

Common Error Categories

💧

Hydration Errors

Server/client mismatch issues

Text mismatch HTML structure

🔄

Routing Errors

Navigation and page issues

404 errors Dynamic routes

🖼️

Image Errors

Next/Image component problems

Domain config Size issues

📦

Build Errors

Compilation and deployment issues

Module errors Type errors

🔹 Hydration Mismatch Error

This error occurs when the HTML rendered on the server doesn't match what React renders on the client. Common causes include using browser-only APIs during server rendering, random values, or date/time that differs between server and client.

❌ Problem Code:

// This causes hydration error
export default function Page() {
  return (
    <div>
      <p>Random: {Math.random()}</p>
      <p>Time: {new Date().toLocaleTimeString()}</p>
    </div>
  )
}

✅ Solution:

'use client'
import { useState, useEffect } from 'react'

export default function Page() {
  const [mounted, setMounted] = useState(false)
  const [time, setTime] = useState('')

  useEffect(() => {
    setMounted(true)
    setTime(new Date().toLocaleTimeString())
  }, [])

  if (!mounted) return null

  return (
    <div>
      <p>Time: {time}</p>
    </div>
  )
}

Result:

✅ No hydration error

✅ Client-only rendering for dynamic content

✅ Consistent server and client output

🔹 Image Domain Not Configured

Next.js Image component requires you to specify allowed domains for external images in your configuration. This security feature prevents unauthorized image sources and ensures only trusted domains can serve optimized images through your application.

❌ Error Message:

Error: Invalid src prop on `next/image`, 
hostname "example.com" is not configured 
under images in your `next.config.js`

✅ Solution:

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    domains: ['example.com', 'cdn.example.com'],
    // Or use remotePatterns for more control
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
      },
    ],
  },
}

module.exports = nextConfig

Usage:

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="https://example.com/photo.jpg"
      alt="Photo"
      width={500}
      height={300}
    />
  )
}

Result:

✅ External images load successfully

✅ Image optimization enabled

✅ Security maintained with domain whitelist

🔹 Module Not Found Error

This error appears when you try to import a package or file that doesn't exist or isn't installed. It's one of the most common errors and usually means you forgot to install a dependency or have a typo in your import path.

❌ Error Message:

Module not found: Can't resolve 'some-package'

✅ Solution 1: Install Missing Package

# Using npm
npm install some-package

# Using yarn
yarn add some-package

# Using pnpm
pnpm add some-package

✅ Solution 2: Fix Import Path

// ❌ Wrong - relative path error
import Component from './components/Button'

// ✅ Correct - include file extension
import Component from './components/Button.tsx'

// ✅ Or use path alias
import Component from '@/components/Button'

Result:

✅ Module imports successfully

✅ Build completes without errors

✅ Application runs normally

🔹 Page Not Found (404)

404 errors occur when Next.js can't find a page at the requested route. This happens with incorrect file names, wrong folder structure, or missing dynamic route parameters. Check your file organization and route naming conventions.

❌ Common Mistakes:

# Wrong file structure
app/
  blog.tsx          # ❌ Wrong - should be in folder
  [id].tsx          # ❌ Wrong - needs parent folder

# Correct file structure
app/
  blog/
    page.tsx        # ✅ Correct - /blog route
  blog/
    [id]/
      page.tsx      # ✅ Correct - /blog/123 route

✅ Correct Implementation:

// app/blog/[id]/page.tsx
export default function BlogPost({ params }) {
  return (
    <div>
      <h1>Blog Post {params.id}</h1>
    </div>
  )
}

// Generate static params for dynamic routes
export async function generateStaticParams() {
  return [
    { id: '1' },
    { id: '2' },
    { id: '3' },
  ]
}

Result:

✅ Routes work correctly

✅ Dynamic pages render properly

✅ No 404 errors