Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Next.js warns that images.domains is deprecated

ErrorThe "images.domains" configuration is deprecated. Please use "images.remotePatterns" configuration instead.

Short answer

Next.js deprecated images.domains in version 14 because it allows every path, port and protocol on a host. Replace each hostname with a remotePatterns entry, using protocol, hostname and pathname. Use ** in the hostname for subdomains, and add a pathname for shared hosts such as image CDNs.

  • Applies to Next.js 15, Next.js 16, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Find every place the old option is set. Besides next.config, a shared config package or a generated config can also add it.

    grep -rn "domains" next.config.*
  2. 2Match what you see, then jump to its fix

    1. 1The deprecation warning appears on next dev and next build, and images still load.The config still lists hostnames under images.domainsFix
    2. 2After the swap, images from a subdomain such as image.example.com answer 400 Bad Request.Subdomains were relied on, but domains has no wildcardsFix
    3. 3The old config allowed a host like res.cloudinary.com with no limit on path.A shared image host is allowed for all accountsFix
    4. 4An image with ?v=123 in the src returns 400 after you set search: ''.Images need a query string and the pattern blocks itFix

What does the error look like?

  • The "images.domains" configuration is deprecated. Please use "images.remotePatterns" configuration instead.
  • next.config.js still has images: { domains: [...] }

Cause 1 of 4

The config still lists hostnames under images.domains

1Check

The docs mark domains as deprecated since Next.js 14. It only accepts hostnames, so it cannot limit protocol, port or path.

grep -n -B2 -A6 "images" next.config.*

2Fix

Turn each hostname into a remotePatterns entry. Write the protocol you really use, and leave port empty unless the image server uses a custom one.

// before
images: { domains: ['assets.acme.com'] }

// after
images: {
  remotePatterns: [
    { protocol: 'https', hostname: 'assets.acme.com', port: '', pathname: '/**' },
  ],
}

3Verify

Restart the dev server and confirm the warning is gone and the images still render.

npm run dev

Confirmed by nextjs.org

Did this fix it?

Cause 2 of 4

Subdomains were relied on, but domains has no wildcards

1Check

domains does not support wildcard matching, so a list of exact subdomains was needed. remotePatterns supports * for one subdomain or segment and ** for any number, at the start of a hostname.

grep -rn "example.com" next.config.*

2Fix

Use a wildcard hostname. The docs note that ** works at the beginning of a hostname and at the end of a pathname, not in the middle.

images: {
  remotePatterns: [
    { protocol: 'https', hostname: '**.example.com', port: '' },
  ],
}

3Verify

Open a page that shows a subdomain image and check it loads.

curl -I 'http://localhost:3000/_next/image?url=https%3A%2F%2Fimage.example.com%2Fa.jpg&w=640&q=75'

Confirmed by nextjs.org

Did this fix it?

Cause 3 of 4

A shared image host is allowed for all accounts

1Check

On a host shared by many customers, domains lets anyone's images pass through your optimizer. The docs say most remote image servers are shared between tenants and recommend strict patterns.

grep -n "cloudinary\|amazonaws\|imgix" next.config.*

2Fix

Limit pathname to your own account folder. A pathname that ends in ** matches everything below that folder.

images: {
  remotePatterns: [
    { protocol: 'https', hostname: 'res.cloudinary.com', pathname: '/my-cloud-name/**' },
  ],
}

3Verify

Load one image from your folder, then try an image from another account path and expect a 400.

npm run build && npm run start

Confirmed by nextjs.org

Did this fix it?

Cause 4 of 4

Images need a query string and the pattern blocks it

1Check

A pattern with search set to an empty string only allows URLs without a query string. Omitting search means ** is implied, which the docs advise against.

grep -rn "search" next.config.*

2Fix

Set search to the exact query string you use, or serve the images without one.

remotePatterns: [
  { protocol: 'https', hostname: 'assets.example.com', search: '?v=1727111025337' },
]

3Verify

Request the image through the app and confirm it loads.

npm run dev

Confirmed by nextjs.org

Did this fix it?

How do I stop it coming back?

  • Write a new external image host as a remotePatterns entry from the start, with protocol and pathname.
  • Keep pathname as narrow as your folder layout allows.
  • Treat the warning as a to-do in CI logs: grep for domains in next.config when you upgrade Next.js.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.