Error Encyclopedia

Next.js Image Optimization Error

Fix common Next.js Image Optimization errors including invalid src, missing domains config, and sharp installation issues.

What Does This Error Mean?

Next.js Image Optimization errors occur when the built-in Image component cannot process or optimize an image. This can be due to missing domain configuration, the optional sharp library, or invalid image sources.

Common Causes

1

Remote image domain not added to next.config.js images.domains

2

Sharp library not installed for production image optimization

3

Invalid image source (relative path instead of absolute or imported)

4

Missing width and height props on Image component

5

SVG files not allowed in Image optimization (use unoptimized)

6

External URL protocol not matching allowed patterns

How to Fix It

Configure remote image domains

Add all external image hosts to next.config.js.

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: "https",
        hostname: "images.example.com",
        port: "",
        pathname: "/**",
      },
    ],
  },
}

Install sharp for production

Sharp is required for production image optimization on non-Vercel deployments.

# Install sharp
npm install sharp

# Verify installation
npx sharp --version

# Next.js will use sharp automatically when available
# In development, Next.js uses squoosh (built-in)

Use proper Image component props

Always provide width, height, and alt attributes.

import Image from "next/image"
import myPic from "../public/photo.jpg"

// ✅ Imported image (automatic width/height)
<Image src={myPic} alt="Description" />

// ✅ Remote image with explicit dimensions
<Image
  src="https://example.com/photo.jpg"
  alt="Description"
  width={800}
  height={600}
/>

// ✅ Unoptimized for SVGs or dynamic images
<Image
  src={svgImage}
  alt="SVG"
  width={100}
  height={100}
  unoptimized
/>

Related Tools

Use these tools to debug and fix this error:

Related Errors

Other common errors in this category: