sharp "Could not load the … module using the … runtime" - Fix in CI

sharp ships platform-specific optional dependencies. If node_modules was installed on one OS/arch (or with optional deps disabled) and run on another, the matching binary is absent and sharp cannot load.

What this error means

At runtime sharp throws "Could not load the sharp module using the <platform> runtime", often after copying node_modules from a host into a Linux container, or after installing with optional dependencies skipped.

Runtime output

Error: Could not load the "sharp" module using the linux-x64 runtime
Possible solutions:
- Ensure optional dependencies can be installed:
    npm install --include=optional sharp
- Ensure your package manager supports multi-platform installation

Common causes

node_modules built for a different platform

Installing on macOS/Windows then copying node_modules into a Linux image leaves the wrong sharp binary; the linux-x64 (or arm64) variant is missing.

Optional dependencies were skipped

sharp’s prebuilt binaries are optional dependencies. --no-optional/--omit=optional or a frozen install that drops them leaves no usable binary.

Architecture mismatch (x64 vs arm64)

Building on x64 and running on arm64 (or vice versa) installs the wrong native variant.

How to fix it

Install sharp on the target platform

Run the install inside the same OS/arch that runs the code, with optional deps enabled.

Terminal

rm -rf node_modules
npm ci --include=optional
# or force the correct platform binaries:
npm install --cpu=x64 --os=linux sharp

Align Docker build and runtime

Run npm ci inside the Dockerfile, not on the host, so binaries match the image.
Set the builder platform to match runtime (--platform=linux/amd64 or arm64).
Keep optional dependencies enabled for image installs.

How to prevent it

Install native deps in the same platform that runs them.
Keep optional dependencies enabled for sharp.
Never ship a host-built node_modules into a different OS/arch.