The next/image component is one of the easiest ways to improve your application's performance. It automatically optimizes images, lazy-loads them, serves modern formats, and helps improve Core Web Vitals scores.

Despite these benefits, it is also one of the most common sources of confusion for developers new to Next.js. Errors like "hostname is not configured," blurry images, layout issues, or images that simply refuse to load almost always come down to a few simple mistakes.

This guide covers the ten most common next/image mistakes and shows you how to fix each one.

What this covers:

• Why images fail to load

• Common sizing and layout mistakes

• Responsive image best practices

• External image configuration

• Performance tips for the Image component

1. Forgetting to Configure External Image Hosts

One of the most common errors looks like this:

Invalid src prop on `next/image`.
Hostname "img.youtube.com" is not configured.

By default, Next.js only permits images from trusted sources. If you are loading images from YouTube, Unsplash, GitHub, Cloudinary, or another external service, you must explicitly allow that hostname in next.config.ts:

images: {
  remotePatterns: [
    {
      protocol: "https",
      hostname: "img.youtube.com",
    },
  ],
},

Modern versions of Next.js use remotePatterns rather than the older domains array. If you are still using domains, switch to remotePatterns, which lets you restrict images by protocol, hostname, port, pathname, and query parameters.

2. Forgetting Width and Height

Unlike a standard HTML <img> tag, the Image component expects explicit dimensions. These help Next.js prevent layout shifts, optimize image delivery, and improve loading performance.

Instead of:

<Image src="/photo.jpg" alt="Photo" />

Use:

<Image
  src="/photo.jpg"
  alt="Photo"
  width={800}
  height={600}
/>

3. Assuming width={0} Is Invalid

Many developers assume width and height must always reflect real pixel dimensions. That is not the case. A valid responsive pattern is:

<Image
  src={image}
  alt="Example"
  width={0}
  height={0}
  sizes="100vw"
  style={{
    width: "100%",
    height: "auto",
  }}
/>

Here, CSS controls the final rendered size while the props satisfy the component's API requirements. This is especially useful when the image dimensions are not known ahead of time.

4. Omitting the sizes Attribute

Responsive images can work without sizes, but they will not be fully optimized. Without it, Next.js cannot determine which image size to serve for a given viewport, and may send a larger file than necessary.

For a full-width image:

sizes="100vw"

For a two-column layout:

sizes="(max-width: 768px) 100vw, 50vw"

Providing an accurate sizes value lets Next.js generate and serve appropriately sized images rather than oversized downloads.

5. Using fill Without a Positioned Parent

A common fill mistake looks like this:

<Image
  fill
  src={image}
  alt="Hero"
/>

The image renders as invisible because the fill prop causes the image to size itself relative to its nearest positioned ancestor. If that ancestor has no position: relative and no explicit height, the image has nothing to fill.

The correct pattern:

<div
  style={{
    position: "relative",
    height: 400,
  }}
>
  <Image
    fill
    src={image}
    alt="Hero"
    style={{ objectFit: "cover" }}
  />
</div>

6. Stretching Images Instead of Preserving Aspect Ratio

Setting both dimensions to 100% without accounting for aspect ratio frequently results in distorted images:

width: 100%;
height: 100%;

Use one of these approaches instead, depending on the layout you want:

/* Scales naturally */
width: 100%;
height: auto;

/* Fills the container and crops */
object-fit: cover;

7. Using <img> Instead of next/image

A standard HTML <img> element works perfectly well, but it bypasses the optimizations that make Next.js applications faster. The Image component provides automatic optimization, responsive image generation, lazy loading, modern format conversion (WebP, AVIF), and reduced layout shift.

Prefer next/image over <img> wherever practical.

8. Expecting Every Image to Load Immediately

The Image component lazy-loads by default, meaning images will not begin loading until they are close to entering the viewport. This is the correct behavior for most images on a page.

For above-the-fold images like hero banners that should be visible the moment the page loads, add the priority prop:

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

This tells Next.js to preload the image rather than waiting for it to enter the viewport. Reserve priority for images the user sees immediately; applying it to every image defeats the purpose.

9. Using Source Images Much Larger Than Necessary

Next.js optimizes images at request time, but starting with a 6000 × 4000 pixel source file and displaying it at 400 pixels wide still wastes resources. Optimization reduces the overhead, but it does not eliminate it entirely.

Choose source images with dimensions that are reasonable for their intended display size. For most content images, anything significantly wider than 2000 pixels is more than enough.

10. Not Reading the Full Error Message

Many next/image errors include a precise description of what went wrong. Before searching online, read the full message in your terminal or browser console.

Common messages and what they mean:

• "Hostname not configured" means you need to add the domain to remotePatterns

• "Invalid src" usually means an empty string or malformed URL is being passed

• "Missing required width" and "Missing required height" mean the props are absent and fill is not set

The error almost always tells you exactly where to look.

Frequently Asked Questions

Is remotePatterns better than domains?

Yes. remotePatterns is the current approach and offers finer control, letting you restrict images by protocol, hostname, port, pathname, and query parameters. The domains array is considered legacy and may be removed in a future version.

Can I use width={0} and height={0}?

Yes, when the rendered dimensions are controlled through CSS and paired with an appropriate sizes value. See mistake 3 above for the full pattern.

Why are my images blurry?

The most common causes are a missing or inaccurate sizes attribute, a low-resolution source file, or CSS that scales the image up beyond its natural size. Check those three things first.

Should every image use priority?

No. Reserve priority for images that are visible immediately when the page loads, such as hero images or prominent banners near the top of the page. Using it on every image prevents the browser from making informed loading decisions.

Key Takeaways

• Configure external image hosts using remotePatterns in next.config.ts.

• Always provide width and height, even if you plan to control the rendered size through CSS.

• width={0} and height={0} are valid when paired with CSS sizing and a sizes attribute.

• The fill prop requires a parent with position: relative and an explicit height.

• Add sizes to responsive images so Next.js can serve the appropriately sized file.

• Use priority only on images visible immediately on page load.

• Read the full error message before searching online; it usually contains the answer.

Conclusion

The next/image component is not difficult to use, but it does have rules that differ from a plain HTML <img> element. Most issues, whether a missing hostname configuration, incorrect sizing, or an invisible fill layout, come down to a small misunderstanding of how the component works and can be fixed with a minor change.

Avoiding these ten mistakes will help you build faster, more reliable Next.js applications while making full use of the framework's built-in image optimization.

If you have run into a next/image issue not covered here, share the error message in the comments.

Which of these mistakes caught you out when you first started using next/image?