next build fails because next/image uses the default loader in a static export
Build fails when output: 'export' is set and next/image is importedShort answer
With output: 'export' there is no server to optimise images on request, and the default next/image loader needs that server. Next.js refuses the build. Either run next start or use a host with image optimisation, configure a custom loader, or set images.unoptimized to true to serve the files as they are.
Fix it fast
1Find out which cause you have
Confirm both ingredients are in your project: an export mode in the config and the next/image component in the code.
grep -n "output" next.config.* grep -rn "next/image" app/ src/ components/ 2>/dev/null | head2Match what you see, then jump to its fix
- 1
output: 'export' in next.config and Image imported from next/image, with no loader setThe default loader needs the Image Optimization API, which an export does not haveFix - 2
You host on plain static hosting and do not need resizing or format conversionKeep the static export and serve images as they areFix - 3
You still want resizing and modern formats on a static hostKeep the static export and optimise through an image serviceFix
- 1
What does the error look like?
Build fails when output: 'export' is set and next/image is importednext/image with the default loader in an exported app
Cause 1 of 3
The default loader needs the Image Optimization API, which an export does not have
1Check
Next.js optimises images on demand, as users request them, not at build time. The default loader relies on that API, so it is not available for exported applications.
grep -n "loader\|unoptimized" next.config.*2Fix
If you want optimisation, drop the static export and run a server with next start, or deploy to a provider that supports Image Optimization. Otherwise use one of the next two fixes.
// next.config.js: remove the export mode
module.exports = {
// output: 'export',
};3Verify
Build and start the production server.
npm run build
npm run startConfirmed by nextjs.org
Cause 2 of 3
Keep the static export and serve images as they are
1Check
unoptimized skips the Image Optimization API and serves the source image as it is, without changing quality, size or format. It can be set for all images in next.config.js.
grep -n "unoptimized" next.config.*2Fix
Set images.unoptimized in the config. Resize and compress the files yourself before you add them.
// next.config.js
module.exports = {
output: 'export',
images: {
unoptimized: true,
},
};3Verify
Build; the export is written to the out folder.
npm run build
ls out | headConfirmed by nextjs.org
Cause 3 of 3
Keep the static export and optimise through an image service
1Check
The static export guide says image optimisation can be used with an export by defining a custom image loader in next.config.js, for example for a service such as Cloudinary.
ls my-loader.* 2>/dev/null2Fix
Set loader to custom, point loaderFile at a module that builds the image URL, and use relative image paths in next/image.
// next.config.js
module.exports = {
output: 'export',
images: {
loader: 'custom',
loaderFile: './my-loader.ts',
},
};
// my-loader.ts
export default function myLoader({ src, width, quality }: {
src: string; width: number; quality?: number;
}) {
return `https://res.cloudinary.com/demo/image/upload/w_${width},q_${quality || 'auto'}${src}`;
}3Verify
Build, then open a page and check in the Network tab that image requests go to the service.
npm run buildConfirmed by nextjs.org
How do I stop it coming back?
- Decide on static export or a server at the start; image optimisation is one of the features that differs.
- Read the Unsupported Features list in the static export guide before adding cookies, rewrites or redirects.
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
Web apps
Apollo Server rejects a request as a potential CSRF
HTTP 400 Bad Request from the GraphQL endpoint
Apollo Server's CSRF prevention is on by default.
3 causes, each with a fixWeb apps
Clerk cannot read its publishable key in a Next.js app
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is undefined
Clerk reads NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY.
3 causes, each with a fixWeb apps
The shell cannot find create-next-app
command not found: create-next-app
create-next-app is not meant to be installed as a shell command.
2 causes, each with a fixWeb apps
ESLint fails with: Cannot find module 'next/babel'
ESLint stops on the first file with a Babel or parser error instead of listing lint results
next/babel is a Babel preset that ships inside the next package.
3 causes, each with a fixWeb apps
Firebase Auth says the API key is not valid
Firebase: Error (auth/api-key-not-valid.-please-pass-a-valid-api-key.)
The apiKey your app sends is either empty, wrong, or blocked.
4 causes, each with a fixWeb apps
Jest fails with SyntaxError: Unexpected token when testing a Next.js component
Jest failed to parse a file.
Jest only understands plain JavaScript until a transform and a few file mappings tell it more.
3 causes, each with a fix