Next.js "Image Optimization using the default loader ... requires sharp" in CI

By Daniel Zoghalchali·Latchkey

Next.js optimizes images with the sharp native module. When sharp is not installed (commonly in standalone output or a slim CI image), the image optimizer throws and the build or runtime image route fails.

What this error means

next build or the standalone server errors with "'sharp' is required ... for Image Optimization" or "Could not load the 'sharp' module using the linux-x64 runtime".

Error: 'sharp' is required to be installed in standalone mode for the image
optimization to function correctly. Read more at:
https://nextjs.org/docs/messages/sharp-missing-in-production

Common causes

sharp is not a dependency of the project

Modern Next.js no longer bundles sharp automatically for standalone output, so if it is not declared it is absent at build or runtime.

The installed sharp lacks the linux-x64 binary

sharp installed on macOS or copied between images may not include the platform binary the Linux runner needs.

How to fix it

Install sharp explicitly

1. Add sharp to dependencies so it ships with the build.
2. Run a clean install on the runner platform so the right binary is fetched.
3. Re-run next build.

npm install sharp
npm ci

Force the correct platform binary in Docker

When building images for linux on a different host, install the platform-specific sharp.

npm install --cpu=x64 --os=linux sharp

How to prevent it

• Declare sharp in dependencies for any project using next/image optimization.
• Install on the target platform so the native binary matches.
• Verify the standalone image serves an optimized image before deploy.

Frequently asked questions

Related guides

References

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