Gatsby "Generating image thumbnails failed" (sharp) in CI

By Kaveh Alemi·Latchkey

gatsby-plugin-image and gatsby-transformer-sharp use the native sharp library to process images. When sharp's prebuilt binary does not match the runner platform or libc, image generation throws and the build fails.

What this error means

The build errors during image processing with "Something went wrong installing the \"sharp\" module" or "Generating image thumbnails failed", often mentioning a missing .node binary or a glibc/musl mismatch.

Something went wrong installing the "sharp" module

Cannot find module '../build/Release/sharp-linux-x64.node'
Possible solutions: ... npm install --platform=linux --arch=x64 sharp

Common causes

A cached or wrong-platform sharp binary

A node_modules cache built on a different OS/arch (or a musl image like Alpine) restored a sharp binary that does not load on the runner.

A partial or offline install of optional binaries

sharp downloads a platform binary at install; a blocked network or --no-optional install leaves it without one.

How to fix it

Reinstall sharp for the runner platform

1. Do a clean install so optional native binaries download for this OS/arch.
2. Avoid restoring a node_modules cache built on a different platform.
3. On Alpine, install the musl build explicitly.

npm install --include=optional sharp
# Alpine: npm install --os=linux --libc=musl --cpu=x64 sharp

Cache the package download, not node_modules

Let setup-node cache the npm download directory so each platform resolves its own sharp binary.

- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'npm'

How to prevent it

• Never restore node_modules built on a different OS or libc.
• Use --include=optional so sharp gets its platform binary.
• Match the runner image (glibc vs musl) to the sharp build you install.

Frequently asked questions

Related guides

References

• Node.js documentation
• npm CLI documentation
• GitHub Actions documentation