sharp module 📦 npm

Error: Could not load the "sharp" module using the linux-x64 runtime

sharp’s native binary for this OS/CPU isn’t installed — usually node_modules installed on another platform (Mac → Linux/Docker).

Seen on: npm

Meaning

sharp ships platform-specific binaries as optional dependencies. Copying node_modules between machines, or installing with --omit=optional, breaks it.

Common causes

  • node_modules copied from macOS into a Linux container
  • Optional dependencies skipped
  • Lockfile generated on another platform without that platform’s package

⚡ Quick fix

  1. Install inside the target environment (npm ci in Docker)
  2. Add .dockerignore for node_modules
  3. npm install --os=linux --cpu=x64 sharp when cross-installing

Detailed fix by platform

Docker

  1. bash
    # .dockerignore
node_modules

How to diagnose

  1. Platform — Where was node_modules installed?
  2. Recent change — Did it start after a deploy, upgrade, or configuration change? Compare with the last working version.

🧠 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.