Next.js Image Optimization Error: Invalid src or missing loader

What causes this error

The next/image component routes all images through Next.js's built-in image optimization API (/_next/image). This API resizes, compresses, and converts images to modern formats (WebP/AVIF) on-demand. For security, Next.js blocks optimization of external images unless their hostnames are explicitly allowlisted in next.config.js remotePatterns. Without this allowlist, any website could abuse your server as a free image proxy. The error also fires when width and height are missing for external images (Next.js cannot infer dimensions from a URL), when the src is an empty string or malformed URL, or when the deployment platform does not support the image optimization API.

How to fix it

1. 01

   step 1

   Add the image hostname to remotePatterns

   If the error says 'hostname is not configured under images in your next.config', add the domain to the remotePatterns array. Use wildcard patterns for CDNs with subdomains. The domains config is deprecated in Next.js 14+ — use remotePatterns instead.

   // next.config.ts
   const nextConfig = {
     images: {
       remotePatterns: [
         {
           protocol: 'https',
           hostname: 'cdn.example.com',
           pathname: '/images/**',
         },
         {
           protocol: 'https',
           hostname: '**.cloudinary.com', // wildcard subdomain
         },
         {
           protocol: 'https',
           hostname: 'lh3.googleusercontent.com',
         },
       ],
     },
   };
   export default nextConfig;

   Copy
2. 02

   step 2

   Provide width and height for external images

   External images (URLs) require explicit width and height props because Next.js cannot read dimensions from a remote URL at build time. If you want responsive sizing, use the fill prop instead and set the parent container's dimensions with CSS.

   import Image from 'next/image';
   
   // Option 1: Explicit dimensions
   <Image
     src="https://cdn.example.com/photo.jpg"
     alt="Description"
     width={800}
     height={600}
   />
   
   // Option 2: Fill mode — image fills its positioned parent
   <div style={{ position: 'relative', width: '100%', height: '400px' }}>
     <Image
       src="https://cdn.example.com/photo.jpg"
       alt="Description"
       fill
       style={{ objectFit: 'cover' }}
     />
   </div>

   Copy
3. 03

   step 3

   Fix the 'Invalid src' error

   This error fires when the src prop is an empty string, undefined, null, or a relative URL without a leading slash. Ensure src always has a valid value. For dynamic images that may be null, provide a fallback or conditionally render the component.

   import Image from 'next/image';
   
   // BAD: src might be undefined
   // <Image src={user.avatar} alt="" width={48} height={48} />
   
   // GOOD: fallback for missing images
   <Image
     src={user.avatar || '/default-avatar.png'}
     alt={user.name}
     width={48}
     height={48}
   />
   
   // GOOD: conditionally render
   {user.avatar && (
     <Image src={user.avatar} alt={user.name} width={48} height={48} />
   )}

   Copy
4. 04

   step 4

   Configure a custom loader for static exports or external CDNs

   If you deploy with output: 'export' (static HTML), the built-in image optimizer is unavailable because there is no server. Use a custom loader that points to your image CDN, or set unoptimized: true to serve images as-is.

   // next.config.ts — for static exports
   const nextConfig = {
     output: 'export',
     images: {
       unoptimized: true, // serve images as-is, no optimization
     },
   };
   export default nextConfig;
   
   // OR use a custom loader for Cloudinary/Imgix:
   // next.config.ts
   const nextConfig = {
     images: {
       loader: 'custom',
       loaderFile: './lib/image-loader.ts',
     },
   };
   export default nextConfig;
   
   // lib/image-loader.ts
   export default function cloudinaryLoader({
     src,
     width,
     quality,
   }: {
     src: string;
     width: number;
     quality?: number;
   }) {
     const params = ['f_auto', 'c_limit', `w_${width}`, `q_${quality || 'auto'}`];
     return `https://res.cloudinary.com/demo/image/upload/${params.join(',')}${src}`;
   }

   Copy

How to verify the fix

• npm run build completes without image optimization errors.
• Images load correctly in the browser — check the Network tab to confirm they route through /_next/image (or your custom loader).
• View page source: img tags have srcset attributes with multiple sizes for responsive loading.
• No broken image icons appear on any page.