_runheed
Sign in

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

Node.js · updated 2026-11-04

Thrown when sharp (used directly, or by Next.js image optimization) is first required and none of its prebuilt binaries match the machine: the runtime in the message (linux-x64, linuxmusl-x64, linux-arm64) is the one that is missing. sharp prints the reason and a list of possible fixes under the message.

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:
    See https://sharp.pixelplumbing.com/install#cross-platform
- Add platform-specific dependencies:
    npm install --os=linux --cpu=x64 sharp

Quick fix

Install dependencies on the platform that runs the code: run the install inside the Docker build or on the server, not on a Mac whose node_modules is then copied. If you have to install for another platform, use npm install --os=linux --cpu=x64 sharp (add --libc=musl for Alpine) and make sure optional dependencies are not omitted.

  1. Read the runtime in the message (linux-x64, linuxmusl-x64 for Alpine, linux-arm64 for Graviton or ARM Macs in Docker).
  2. Stop copying node_modules from a developer machine: add node_modules to .dockerignore and run npm ci in the image.
  3. Don't install with --omit=optional or --no-optional: sharp's binaries are optional dependencies.
  4. Installing for a different platform on purpose: npm install --os=linux --cpu=x64 sharp (plus --libc=musl on Alpine).
  5. pnpm and yarn: configure the supported architectures so the lockfile includes the Linux binaries.
dockerfile
FROM node:22-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
# Installed inside the image, so sharp gets the linux-x64 binary
RUN npm ci

FROM node:22-slim
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
CMD ["node", "server.js"]

# .dockerignore
# node_modules

Why it happens

node_modules installed on another OS

Installing on macOS fetches the darwin binary only. Copying that node_modules into a Linux image or rsyncing it to a server leaves sharp without a linux binary.

Optional dependencies skipped

sharp's platform packages (@img/sharp-linux-x64 and friends) are optionalDependencies; --omit=optional, NODE_ENV-based flags or some CI caches drop them.

Alpine (musl) vs glibc

A node_modules installed on Debian or Ubuntu has the glibc binary; Alpine needs linuxmusl-x64, and the reverse.

Old OS or Node.js

If the message also mentions a glibc or CXXABI version or a Node.js version, the server is older than the prebuilt binaries support; sharp prints the found and required versions.

Other fixes

  • Next.js standalone output needs sharp in production for next/image; install it in the image the standalone server runs in.
  • On platforms without a prebuilt binary, sharp can fall back to WebAssembly: npm install sharp @img/sharp-wasm32.

Same error, other wording

  • Error: Could not load the "sharp" module using the linuxmusl-x64 runtime
  • Error: Could not load the "sharp" module using the linux-arm64 runtime
  • Error: Something went wrong installing the "sharp" module

Let your coding agent catch the next one

Runheed records this error in production with the stack trace, the breadcrumbs before it and the agent session that shipped the code, and serves it to Claude Code, Cursor or any MCP client. With it connected, you can ask:

> Find the "Could not load the sharp module" errors in production, tell me which runtime the server needs, and fix the build so dependencies are installed for that platform instead of copied from a dev machine.

Plans from $29/moSee what your agent readsSee the setupCancel any time from the billing portal

Related errors

More in Imports and modules

References: sharp docs: installation (cross-platform), sharp source: the load error and its help text