Next.js Image Optimisation Not Working: How to Fix It

What the Next.js image optimiser does

The next/image component does not serve your original file. It writes an <img> tag whose srcset points at a built-in endpoint, /_next/image, with the source address, a width and a quality in the query string. When a browser requests one of those addresses, the Next.js server fetches the original, resizes it, converts it to a modern format the browser accepts, caches the result and sends it back.

/_next/image?url=%2Fimages%2Fsofa.jpg&w=828&q=75

So optimisation depends on three things being in place: a running Next.js server or a hosting platform that provides the same endpoint, permission to fetch the source image, and an image library on the server to do the resizing. Break any one of them and you get broken images, errors in the logs, or full-size originals served to phones.

How to tell whether optimisation is running

Open the page in Chrome, open DevTools, choose the Network tab and filter by Img. Click an image request and read its address and response headers. An optimised image looks like this:

Request URL:   https://www.example.com/_next/image?url=%2Fimages%2Fsofa.jpg&w=828&q=75
Status:        200
content-type:  image/webp
cache-control: public, max-age=14400, must-revalidate
x-nextjs-cache: HIT

If the request goes straight to /images/sofa.jpg instead, the component is not optimising that image. If the content-type is still image/jpeg for a browser that accepts WebP, the format step is not happening. The x-nextjs-cache header shows whether the optimised file came from the cache: MISS on the first request and HIT afterwards is correct. MISS every time means the cache is not working.

You can test the endpoint directly from the command line, which removes the browser from the picture:

curl -sI "https://www.example.com/_next/image?url=%2Fimages%2Fsofa.jpg&w=828&q=75" \
  -H "Accept: image/avif,image/webp,*/*"

# compare with the original
curl -sI https://www.example.com/images/sofa.jpg | grep -i content-length

A 400 response with a short text body usually names the problem, such as a width that is not allowed or a URL parameter that is missing. A 500 or 502 points at the server side: the source could not be fetched, or the image library failed. Check the server logs at the same moment, because Next.js writes the underlying error there.

The key configuration changes

Allow remote image hosts narrowly

Images from another domain, such as a headless CMS or a product feed, must be allowed in next.config.js. The older images.domains option is deprecated; use remotePatterns and keep each pattern as narrow as you can:

// next.config.js
module.exports = {
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'images.example.com', pathname: '/products/**' },
      { protocol: 'https', hostname: 'cdn.examplecms.io', pathname: '/uploads/**' },
    ],
    formats: ['image/avif', 'image/webp'],
  },
};

A wildcard such as hostname: '**' makes the error go away, but it lets anyone use your server to resize images from any site, which costs you processing time and, on paid hosting, money. Restart the development server after changing the config, because it is only read on start.

Static export needs its own loader

With output: 'export' there is no Next.js server after the build, so the default optimiser cannot run and the build stops with an error saying the default loader is not compatible with export. You have two choices. Point a custom loader at an image CDN that resizes on request:

// next.config.js
module.exports = {
  output: 'export',
  images: { loader: 'custom', loaderFile: './image-loader.js' },
};

// image-loader.js
export default function imageLoader({ src, width, quality }) {
  return `https://images.example.com${src}?w=${width}&q=${quality || 75}&fm=webp`;
}

Or set images.unoptimized: true and resize images yourself at build time, keeping several widths of each file. The first choice keeps responsive images working; the second is fine for small sites with few images.

Describe the slot with sizes

Images that use fill or a responsive layout need a sizes prop. Without it the browser assumes the image is as wide as the screen and picks a large file. Describe the real width at each breakpoint:

<Image src="/images/sofa.jpg" alt="Grey three-seat sofa"
  fill sizes="(min-width: 1024px) 25vw, (min-width: 640px) 50vw, 100vw" />

Self-hosting, Docker and the image library

When you run Next.js yourself with next start or a standalone build, the optimiser uses the sharp package to resize and convert images. Recent versions of Next.js install it for you, but it is a native module with a separate binary per operating system and processor. That causes trouble in two common setups.

• Docker images built from a lock file made on a Mac. The installed binary is for macOS, not the Linux image. Run the install inside the container, or install sharp with the correct platform flags.
• Standalone builds. output: 'standalone' copies only the files it traces as needed. Check that node_modules/sharp is present in the output folder you deploy.

# inside the running container or server
node -e "require('sharp'); console.log('sharp ok')"
ls .next/standalone/node_modules | grep sharp

The optimised files are cached on disk in .next/cache/images. If that folder is not writable, which happens with read-only container file systems, or if it is wiped on each deploy, every request is resized again. Mount a writable volume for it, and put a CDN in front so most requests never reach Node at all. The minimumCacheTTL setting controls the shortest cache time; its default has changed between versions, so set it explicitly if you rely on it.

If the server is slow overall, image resizing makes it worse, because each first request for a size uses processor time. Our guide to high time to first byte covers the server side, and fixing image CDN setup covers handing the work to a dedicated service.

Platform notes

Middleware is a frequent hidden cause. If your middleware matcher runs on every path, it may redirect or rewrite requests to /_next/image, for example to add a locale prefix or to require a login. Exclude it in the matcher:

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};

If you use a basePath, the endpoint moves under it, such as /shop/_next/image, so any proxy rules need to match that path. For wider Next.js performance work, see fixing images in Next.js and Core Web Vitals on Next.js.

A worked example

A small furniture shop moved its Next.js site from Vercel to a static host to save costs, with output: 'export' added to the config. The build failed with the loader error. A developer added images: { unoptimized: true } to get it building, and the site went live.

The site worked, but product listing pages now sent the original 2,400 pixel photos, around 900 KB each, to every phone. A category page with 24 products went from about 1.1 MB of images to over 20 MB, and mobile LCP rose from 2.1 to 5.8 seconds.

The fix was to remove unoptimized, add a custom loader file pointing at the shop's existing image CDN with the requested width and quality, and add a sizes prop to the product grid. No page components changed apart from the grid. After the rebuild, the Network panel showed WebP files of 30 to 60 KB at the widths each layout needed, and mobile LCP came back to 2.3 seconds.

The fix, step by step

Edge cases worth knowing

• SVG files are not optimised by default. Vector images do not need resizing, and the optimiser refuses them unless dangerouslyAllowSVG is set. Usually it is simpler to mark SVGs unoptimized.
• Animated GIFs are passed through without conversion. Convert large ones to video instead.
• Quality values may be restricted in newer versions with images.qualities. A quality the config does not list is rounded to the nearest allowed value.
• Local images with query strings, such as /hero.jpg?v=2, may need images.localPatterns in recent versions.
• Images on private IP addresses, such as a CMS on an internal network, are blocked by default in newer releases for security reasons.
• Source images that are too large, in pixels or file size, can make the optimiser slow or fail. Keep originals to a sensible size, say 2,500 pixels on the long side.

Keeping image optimisation working

• Add a check to your deploy process that requests one known /_next/image address and fails if the response is not 200 and a modern format.
• Keep remote patterns in code review. A pattern widened to fix one error is easy to forget.
• Search the code for unoptimized before each release; it is often left in from testing.
• After a Next.js upgrade, read the image section of the release notes, as defaults such as cache time and allowed qualities have changed between major versions.
• Watch mobile LCP in your field data. A sudden rise after a deploy is often an image setting.

For the wider picture on image weight and formats, see choosing the right image format and fixing oversized images.