Next.js Image Remote Patterns

Use images.remotePatterns in next.config.js to allow externally hosted images used by next/image. A pattern can restrict the protocol, hostname, port, pathname, and query string. The remote image URL must match every configured component exactly when the default Next.js image optimizer is used.

The narrowest useful configuration is usually safest. For example:

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        port: '',
        pathname: '/account123/**',
        search: '',
      },
    ],
  },
}

module.exports = nextConfig

This permits HTTPS URLs on assets.example.com below /account123/, with no custom port and no query string. Replace those values with the URLs your application actually uses. The official Image Component reference describes remotePatterns as the allowlist for specific external paths and says that domains is deprecated since Next.js 14. Read the Next.js Image Component API reference.

How remotePatterns matching works

Next.js compares the source URL against the pattern’s URL components:

Component	Example	What must match
protocol	`https`	The URL scheme. `http` and `https` are different.
hostname	`cdn.example.com`	The host, including subdomain. A sibling subdomain does not match.
port	`''` or `3000`	The exact port. An empty string means the default port.
pathname	`/images/**`	The path and supported wildcard scope.
search	`''` or `?v=2`	The query string policy. Matching is exact.

If a field is omitted in the object form, Next.js treats it as broadly matching. That can allow URLs your application did not intend to optimize, so specify fields whenever practical.

Path wildcards

* matches one pathname segment.
** matches any number of pathname segments only at the end of a pathname pattern.
A double-star wildcard cannot appear in the middle of a pathname pattern.

For example, /images/* can match /images/logo.png but not /images/products/logo.png. /images/** can match both. Keep the path prefix as specific as your source layout permits.

Hostname wildcards

A single * matches one subdomain label. A leading ** can match multiple subdomain labels. Wildcards are supported only in the positions documented by Next.js; do not place ** in the middle of a hostname.

Query-string matching

The search property is exact and includes the leading question mark:

Configuration	Result
`search: ''`	Rejects URLs with query parameters.
`search: '?v=2'`	Requires exactly `?v=2`.
Omitted `search`	Allows query strings broadly in the object form.

Search globs are not supported. If your CDN adds changing cache-busting parameters, either allow searches deliberately or use a stable, query-free image URL.

Complete configuration examples

Allow one exact image host and path

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.example.com',
        port: '',
        pathname: '/products/**',
        search: '',
      },
    ],
  },
}

module.exports = nextConfig

Allow a development server on a custom port

const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'http',
        hostname: 'localhost',
        port: '3001',
        pathname: '/uploads/**',
        search: '',
      },
    ],
  },
}

module.exports = nextConfig

Development URLs commonly fail because the configured port is missing or differs from the port in the actual src URL.

Allow an exact version query string

const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'cdn.example.com',
        port: '',
        pathname: '/assets/**',
        search: '?v=2',
      },
    ],
  },
}

module.exports = nextConfig

URL-constructor form

Current Next.js documentation also shows a URL form:

const nextConfig = {
  images: {
    remotePatterns: [
      new URL('https://assets.example.com/account123/**'),
    ],
  },
}

module.exports = nextConfig

In this form, the URL’s empty search property does not allow search parameters. Use the form supported by the Next.js version installed in your project. The error reference documents the URL-constructor approach for current versions and object-form configuration for earlier versions.

Use the pattern with next/image

import Image from 'next/image'

export default function ProductCard() {
  return (
    <Image
      src='https://images.example.com/products/widget.png'
      alt='Widget'
      width={800}
      height={600}
    />
  )
}

Remote files are not available to Next.js during the build. Give the component a width and height, or use the supported fill layout with a positioned parent, so the browser can reserve layout space. Host authorization and image sizing are separate concerns: a matching pattern does not remove the need for dimensions.

Using fill for responsive images

import Image from 'next/image'

export default function Hero() {
  return (
    <div style={{ position: 'relative', aspectRatio: '16 / 9' }}>
      <Image
        src='https://images.example.com/hero.jpg'
        alt='Product dashboard'
        fill
        sizes='(max-width: 768px) 100vw, 768px'
        style={{ objectFit: 'cover' }}
      />
    </div>
  )
}

Why the unconfigured-host error appears

The diagnostic is commonly shown as next/image Un-configured Host. Check the complete URL printed in the error against the configured pattern character by character. Matching is exact and case-sensitive.

Copy the complete image URL, including its query string, from the failing src.
Compare http versus https.
Compare the full hostname, including www, CDN, or tenant subdomains.
Compare the port, especially in local development.
Compare the pathname against the glob.
Decide whether the query string should be blocked, allowed broadly, or matched exactly.
Restart the Next.js development server after changing next.config.js.

Symptom	Likely cause	Fix
Works in the browser but not in `next/image`	The host is not in `remotePatterns`.	Add a precise matching pattern and restart Next.js.
Only production fails	Production uses a different CDN hostname or path.	Configure the deployed URL, not only the local URL.
Local images fail	The configured port or protocol differs.	Match the actual development URL exactly.
Adding a query parameter breaks the image	`search: ''` blocks queries, or an exact search value differs.	Remove the parameter, omit `search` intentionally, or configure the exact query.
A nested path fails	`*` matches one segment only.	Use a trailing `/**` when nested paths are legitimate.
A sibling subdomain fails	The hostname pattern matches only the configured host.	Add the required host or a supported leading wildcard.
Layout shifts or dimensions are required	Remote authorization succeeded, but sizing is missing.	Provide `width`/`height` or use `fill`.
Authenticated origin returns an error	The default loader does not forward request headers.	Use `unoptimized` where appropriate, or expose an image URL that does not require forwarded authentication headers.

Do not use domains as a new configuration

The older images.domains option is deprecated since Next.js 14. It cannot express wildcards or restrictions for protocol, port, pathname, or query strings. Migrate to remotePatterns so the allowlist reflects the URLs your application really needs.

Security and maintenance checklist

Use HTTPS unless an HTTP origin is required for local development.
Restrict the hostname to the actual image origin.
Restrict the pathname to an image directory or tenant prefix.
Choose an explicit query-string policy.
Review patterns when a CDN, tenant, or asset path changes.
Avoid a broad pattern copied from a temporary debugging fix.
Keep dimensions or fill configuration beside the component.
Verify the exact Next.js version before adopting URL-constructor syntax.

Performance, reliability, and cost considerations

remotePatterns controls whether Next.js may optimize a source; it does not guarantee that the origin is fast, available, or cacheable. The optimizer still depends on the remote server returning a valid image within the request lifecycle.

Performance: narrow paths reduce accidental optimization requests. Use appropriate sizes values with fill so the browser does not download unnecessarily large variants.
Reliability: make sure every deployment uses the same hostname and path policy. A CDN migration can create a production-only failure even when the component code is unchanged.
Authentication: the default loader does not forward headers to fetch the source. Plan for public, signed, or otherwise accessible image URLs when using optimization.
Cost: remotePatterns itself has no separate Next.js charge. Your image origin, CDN, hosting, and image-optimization provider may have their own transfer or request costs.
Debugging: test one literal URL first, then add the minimum wildcard required by your content model.

Or skip the browser setup

If your goal is to capture the final rendered page rather than configure image optimization inside the application, ScreenshotNeo returns a screenshot or PDF with one GET request. See the ScreenshotNeo API documentation.

curl -G 'https://api.screenshotneo.com/v1/shot' -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get('https://api.screenshotneo.com/v1/shot', params={'access_key': 'YOUR_API_KEY', 'url': 'https://stripe.com'}, timeout=90)
open('shot.webp', 'wb').write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots per month are free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.

FAQ

Can I allow every image from a domain?

You can use a broad pathname pattern, but a specific host and path is safer. Add only the URL space your application needs.

Why does a URL with the same host still fail?

Protocol, port, pathname, and query-string differences also matter. Compare the complete URL, not only the hostname.

Should I use `domains` for compatibility?

Use the configuration supported by your project’s Next.js version, but treat domains as the older, less precise option. Current documentation recommends remotePatterns.

Does remotePatterns download the image during build?

No. Remote files are fetched at runtime by the image loader, so provide dimensions or use fill for predictable layout behavior.

Can remotePatterns forward authorization headers?

No. The default loader does not forward headers when fetching the source. Authenticated sources may need unoptimized or a separately accessible image URL.

What should I check after changing next.config.js?

Restart the development server, verify the deployed hostname and port, and test a literal URL that includes the same path and query behavior as production.