Next.js "Image Optimization ... not compatible with `next export`" in CI

By Daniel Zoghalchali·Latchkey

A static export has no server to optimize images at request time. With output: 'export' and next/image's default loader, next build fails and tells you to set images.unoptimized or configure a custom loader.

What this error means

next build fails with "Image Optimization using the default loader is not compatible with { output: 'export' }", naming images.unoptimized as the fix.

Error: Image Optimization using the default loader is not compatible with
`{ output: 'export' }`.

Possible solutions:
  - Set images.unoptimized = true ...
  - Use a custom image loader ...
Read more: https://nextjs.org/docs/messages/export-image-api

Common causes

Static export cannot run the default image optimizer

output: export produces static files only; the default loader needs a running server, which export does not provide.

No unoptimized flag or custom loader is configured

Without images.unoptimized or a loader, Next has no way to serve next/image in a static export.

How to fix it

Set images.unoptimized for static export

1. Add images: { unoptimized: true } to next.config.
2. Confirm output: 'export' is intentional.
3. Re-run next build.

// next.config.js
module.exports = {
  output: 'export',
  images: { unoptimized: true },
}

Use a custom image loader

Point next/image at an external optimization service via a custom loader instead of disabling optimization.

// next.config.js
images: { loader: 'custom', loaderFile: './loader.ts' }

How to prevent it

• Set images.unoptimized (or a loader) whenever you use output: export.
• Decide between static export and a server runtime up front.
• Verify images render in the exported static output.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation