How do I use next/image with external images and avoid 'hostname not configured' errors?

next/image only optimises remote URLs that you explicitly allow, to prevent abuse of your optimiser.

// next.config.ts
import type { NextConfig } from "next";
const config: NextConfig = {
  images: {
    remotePatterns: [
      { protocol: "https", hostname: "cdn.example.com", pathname: "/uploads/**" },
    ],
  },
};
export default config;

images.domains is deprecated in favour of remotePatterns. Restart the dev server after changing config.

Avoiding layout shift

Give dimensions, or fill a sized parent:

import Image from "next/image";

<Image src="https://cdn.example.com/uploads/a.jpg" alt="Team photo" width={800} height={450} />

<div className="relative aspect-video">
  <Image src={url} alt="" fill sizes="(min-width: 768px) 50vw, 100vw" className="object-cover" />
</div>

Tips

• Add priority only to the above-the-fold (LCP) image. Newer versions also accept preload; check your version.
• Always set sizes with fill or responsive images, or the browser may download an oversized file.
• Local files imported statically get width, height and blur placeholder automatically.
• For SVGs and already-optimised images use unoptimized.
• Self-hosted deployments need sharp for good performance (installed automatically by Next 15 in most setups).
• images.qualities / formats: ["image/avif","image/webp"] tune output.

Pitfall: if the remote server blocks hotlinking or is slow, the optimiser returns 400/504. Fetch it yourself in a route or copy images to your own storage.

To shrink sources before upload, try the image compressor.