Node.js "Could not load the sharp module" - Platform Binary Missing in CI

sharp loads a platform-specific native binary published as an optional dependency. When the install happened on a different platform, optional deps were skipped, or the cache carried the wrong arch, the binary for the CI runner is missing and sharp fails to load.

What this error means

A build or runtime step fails with "Could not load the sharp module using the <platform> runtime". The package is installed, but the matching native binary for the runner arch is absent.

node

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

Common causes

Install happened on a different platform

A lockfile or node_modules built on macOS/Windows (or a different arch) lacks the linux-x64/arm64 binary the runner needs.

Optional dependencies were skipped

sharp ships its binaries as optional deps. An install with --no-optional or a cache restored from another platform omits them.

How to fix it

Install sharp for the runner platform

Reinstall sharp including optional deps on the CI runner so the correct binary is fetched.

workflow

npm install --include=optional sharp
# or force the platform explicitly
npm install --cpu=x64 --os=linux sharp

Key caches by platform/arch

Ensure any node_modules cache is scoped to the OS and arch so a foreign-platform binary is never restored.

Include runner.os and arch in the cache key.
Do not share node_modules caches across platforms.
Reinstall on platform mismatch rather than reusing the cache.

How to prevent it

Include optional dependencies when installing native modules.
Scope dependency caches by OS and architecture.
Install on the same platform that runs the job.