'sharp' is required to be installed in standalone mode Next.js Origin: On your device Last updated 5 Nov 2026

Next.js: Error: 'sharp' is required to be installed in standalone mode for the image optimization to function correctly

In production/standalone builds, Next.js needs the sharp package to optimise images.

Exact message you may see 'sharp' is required to be installed in standalone mode for the image optimization to function correctlyError: 'sharp' is required to be installed in standalone modesharp is required Next.js standalone
Explore the map of this error Full error map →
Seen on: Next.js Docker Node.js

Meaning

Install it (npm i sharp) as a dependency (Next 15 bundles it automatically in many cases; Docker with Alpine may need platform-specific binaries). In standalone Docker images copy node_modules/sharp or set NEXT_SHARP_PATH. Without it images are served unoptimized or fail.

Common causes

  • sharp not in dependencies
  • Docker multi-stage copy missing sharp
  • Alpine/arm64 binary mismatch
  • Standalone output without traced sharp
  • Using npm ci --omit=optional

⚡ Quick fix

  1. npm install sharp and rebuild
  2. Dockerfile: install in the runner stage or set NEXT_SHARP_PATH
  3. Don't omit optional dependencies

Detailed fix by platform

Docker

  1. RUN npm i sharp && ENV NEXT_SHARP_PATH=/app/node_modules/sharp

How to diagnose

  1. sharp — Installed?
  2. Image — Docker standalone?
  3. Optional — Omitted?

🔧 Still not fixed?

Many errors look alike. If the steps above didn’t solve it, one of these is probably what you’re facing:

Where this error sits

Origin: On your device. Errors that are often confused with or caused by this one (click to open):

_next/image 400 / upstream image response failed — Next.js: ⨯ upstream image response failed for https://example.com/a.jpg 404 / url parameter is not allowed (Next.js)_next/image 400 / ups…Conflicting app and page file was found — Next.js: ⨯ Conflicting app and page file was found, please remove the conflicting files to continue: "pages/index.tsx" - "app/page.tsx" (Next.js)Conflicting app and p…CORS error calling Next.js API route / route handler — Browser: Access to fetch at 'https://api.example.com/api/data' from origin 'https://app.example.com' has been blocked by CORS policy (Next.js route handler) (Next.js)CORS error calling Ne…EBADPLATFORM — npm ERR! code EBADPLATFORM — notsup Unsupported platform for fsevents: wanted {"os":"darwin"} (current: {"os":"linux"}) (npm)EBADPLATFORMesbuild wrong platform — You installed esbuild for another platform than the one you're currently using. (npm)esbuild wrong platformImage with src must use "width" and "height" properties or "fill" — Next.js: Image with src "https://example.com/a.jpg" must use "width" and "height" properties or "fill" property (Next.js)Image with src must u…invalid ELF header — Error: /app/node_modules/bcrypt/lib/binding/bcrypt_lib.node: invalid ELF header (npm)invalid ELF headernext build: fetch failed ECONNREFUSED (build-time API) — Next.js: Error occurred prerendering page "/blog" TypeError: fetch failed { cause: Error: connect ECONNREFUSED 127.0.0.1:3000 } (Next.js)next build: fetch fai…'sharp' i…

Explore the map of this error Full error map →

🧠 Still stuck? Analyze your error

Paste the full message, response headers or stack trace — we'll detect the platform and point to the most likely cause.

💬 What worked for others

No tips yet — did something else fix this for you?

Share what worked for you

Tips are checked by an editor before they appear. Links are removed.