Fix next/image Hostname Not Configured in Next.js

You drop a remote image into <Image> and the page explodes:

Invalid src prop (https://cdn.example.com/photo.jpg) on `next/image`,
hostname "cdn.example.com" is not configured under images in your
next.config.js

next/image strictly allow-lists the hosts it will optimize — remote image servers are often shared between tenants, so allow-listing protects your optimizer from being pointed at arbitrary URLs. The fix is one config block, but the matching is unforgiving.

{ name: "Next.js", version: "12.3+ (remotePatterns)" },
{ name: "next/image", version: "App & Pages Router" },
]} />

The fix: images.remotePatterns

Add the host with explicit fields:

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

Then restart the dev server — next.config is read once at startup and is not hot-reloaded.

Every part of the URL is matched exactly and case-sensitively:

• Protocol — http ≠ https
• Hostname — example.com ≠ www.example.com ≠ assets.example.com
• Port — if present (:3000 in dev), it must be included
• Pathname — must be covered by the glob; /images/ does not match /images/photo.jpg, you need /images/**

Wildcard rules

* and ** behave differently — and ** only works at the edges:

• * — a single path segment, or a single subdomain
• ** — any number of trailing path segments, or any number of leading subdomains

// allows image.example.com, cdn.example.com, etc.
{ protocol: 'https', hostname: '**.example.com' }

Omitting protocol, port, pathname, or search makes them wildcard — the docs explicitly call this not recommended for security. In particular, omitting search allows all query strings.

Since v15.3.0 you can pass URL objects: remotePatterns: [new URL('https://cdn.example.com/photos/**')]. On older versions, use the object form.

Why not images.domains?

You'll see older answers using images.domains: ['cdn.example.com']. It still works, but the official docs mark it deprecated since Next.js 14 "in favor of strict remotePatterns in order to protect your application from malicious users." domains is a flat hostname list with no wildcard, protocol, port, or pathname control. Migrate:

wrong="images: { domains: ['cdn.example.com'] } // deprecated since Next 14, no protocol/port/path control"
right="images: { remotePatterns: [{ protocol: 'https', hostname: 'cdn.example.com', pathname: '/photos/**' }] }"
/>

Escape hatches (and their cost)

• unoptimized — a prop (or images.unoptimized: true globally) that skips the optimization pipeline and bypasses the allow-list. Right for tiny images, SVGs, or images that need auth headers (the optimizer doesn't forward them). Tradeoff: no resizing, no format conversion, no optimized caching.
• loader / loaderFile — offload optimization to Cloudinary, Imgix, Supabase, etc. via a function ({ src, width, quality }) => string. Tradeoff: a custom loaderFile requires Client Components and hands optimization to a third party.

• The image needs authentication — the built-in optimizer doesn't forward headers; use unoptimized or a custom loader.
• You're on Next.js before 12.3 — remotePatterns isn't stable there; the search prop needs 14.2.14+, and URL-object shorthand needs 15.3.0+.

Official references: next/image "Un-configured Host" error, Image component / remotePatterns, images config.

Related Articles

• Fix Cumulative Layout Shift from next/image
• Set the next/image Component to 100% Height
• Deploy Next.js 15 to Vercel Without Environment Variable Errors

Frequently Asked Questions

How do I fix "hostname is not configured under images"?

Add the host to images.remotePatterns in next.config with the exact protocol, hostname, port, and pathname, then restart the dev server.

Should I use images.domains or images.remotePatterns?

Use remotePatterns. images.domains was deprecated in Next.js 14 in favor of the stricter, more capable remotePatterns.

Why does it still fail after I added the domain?

Matching is exact and case-sensitive: http vs https, a subdomain mismatch, a missing port, or a too-narrow pathname all block it. And restart the dev server — next.config is read only at startup.

Originally published at https://www.iloveblogs.blog