Next.js Image Optimization Error Fix

In this tutorial, you'll learn about Next.js Image Optimization Error Fix. We cover key concepts, practical examples, and best practices.

The Problem

Next.js Image component throws Error: Invalid src prop or hostname "example.com" is not configured under images. The built-in image optimization requires explicit configuration for external image sources.

Quick Fix

Step 1: Configure remote image domains

// next.config.js — Wrong: missing images config
module.exports = { };

// Right
module.exports = {
    images: {
        domains: ['example.com', 'cdn.example.com'],
    },
};

Expected output: External images from configured domains load correctly.

Step 2: Use remotePatterns for stricter matching

module.exports = {
    images: {
        remotePatterns: [
            {
                protocol: 'https',
                hostname: '**.example.com',
                port: '',
                pathname: '/images/**',
            },
        ],
    },
};

Expected output: Only images matching the pattern are optimized.

Step 3: Set width and height on Image component

// Wrong — missing dimensions
<Image src="/hero.jpg" alt="Hero" />

// Right
<Image
    src="/hero.jpg"
    alt="Hero"
    width={1200}
    height={600}
/>

Expected output: The Image component reserves space and prevents layout shift.

Step 4: Use fill for dynamic dimensions

// Right for responsive containers
<div style={{ position: 'relative', width: '100%', height: '400px' }}>
    <Image
        src="/hero.jpg"
        alt="Hero"
        fill
        style={{ objectFit: 'cover' }}
    />
</div>

Expected output: The image fills the parent container without explicit width/height.

Step 5: Disable optimization for unoptimized sources

// For SVGs or already-optimized images
<Image
    src="/icon.svg"
    alt="Icon"
    width={24}
    height={24}
    unoptimized
/>

Expected output: The SVG is served as-is without Next.js image processing.

Step 6: Unoptimize all images in config

module.exports = {
    images: {
        unoptimized: true,
    },
};

Use this for static exports or when using an external CDN.

Step 7: Check for sharp installation

Next.js uses sharp for image optimization. If missing:

npm install sharp

Expected output: Image optimization works in production.

Prevention

• Configure images.domains or images.remotePatterns before using external images
• Always provide width and height for static images
• Use fill with a positioned parent for responsive images
• Install sharp for production image optimization

Common Mistakes with image error

1. Forgetting deriving (Show, Eq) on custom data types needed for debugging
2. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
3. Using head and tail instead of pattern matching, causing runtime errors on empty lists

These mistakes appear frequently in real-world NEXTJS code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ