Failed to locate or install Sharp binary for functions execu

Error message

Failed to locate or install Sharp binary for functions execution platform/arch (${functionsTarget.platform}/${functionsTarget.arch})

What it means

Symmetric to the lmdb check, after resolving sharp's package info Gatsby requires the sharp native binary to be already present for the functions target. If sharpPackageInfo.needToInstall is true, it throws because the bundler cannot fetch/install a native sharp binary at bundle time. When present, sharp's package location is aliased into the webpack bundle via dynamicAliases['sharp$'].

Source

Thrown at packages/gatsby/src/schema/graphql-engine/bundle-webpack.ts:397

  )

  if (!lmdbPackageInfo) {
    throw new Error(`Failed to find required LMDB binary`)
  } else if (functionsTarget.platform === `linux`) {
    // function execution platform is primarily linux, which is tested the most, so we only force that specific binary
    // to not cause untested code paths
    if (lmdbPackageInfo.needToInstall) {
      throw new Error(
        `Failed to locate or install LMDB binary for functions execution platform/arch (${functionsTarget.platform}/${functionsTarget.arch})`
      )
    }

    forcedLmdbBinaryModule = `${lmdbPackageInfo.packageLocation}/node.abi83.glibc.node`
  }

  if (sharpPackageInfo) {
    if (sharpPackageInfo.needToInstall) {
      throw new Error(
        `Failed to locate or install Sharp binary for functions execution platform/arch (${functionsTarget.platform}/${functionsTarget.arch})`
      )
    }
    dynamicAliases[`sharp$`] = sharpPackageInfo.packageLocation
  }

  const compiler = webpack({
    name: `Query Engine`,
    // mode: `production`,
    mode: `none`,
    entry: path.join(__dirname, `entry.js`),
    output: {
      path: outputDir,
      filename: `index.js`,
      libraryTarget: `commonjs`,
    },
    target: `node`,
    externalsPresets: {

View on GitHub (pinned to 8b06340921)

Solutions

Install dependencies in an environment matching the functions target so sharp's prebuilt binary is downloaded (e.g. build inside the target Docker image).
Ensure optionalDependencies/native packages are not pruned by your package manager or CI cache.
For alpine/musl, install the musl sharp build or switch the image to glibc-based.
Pin sharp to a version shipping a binary for your target arch.

Example fix

# before - sharp linux binary missing when cross-building
# after
docker run --rm -v "$PWD":/srv -w /srv node:18 bash -lc "npm ci && gatsby build --functions-platform=linux --functions-arch=x64"

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check sharp's binary for the target is on disk.
function sharpBinaryPresent() {
  try {
    const dir = path.join(path.dirname(require.resolve('sharp')), '..', 'build', 'Release')
    return fs.existsSync(dir) && fs.readdirSync(dir).some(f => f.endsWith('.node'))
  } catch { return false }
}

Type guard

function hasFunctionsTarget(t) { return !!t?.platform && !!t?.arch }

Prevention

Build functions in the same OS/arch family you will deploy to.
Do not strip sharp's platform packages from CI caches.
For musl/alpine, use sharp's musl build or a glibc image.

When it happens

Trigger: installMissing returns a sharpPackageInfo whose needToInstall is true for the functions target platform/arch. Reached when sharp's prebuilt binary for the target is listed but not actually present in node_modules at the expected location.

Common situations: Cross-building functions (e.g. linux target from macOS) where the linux sharp binary is not installed; CI caches stripping sharp's platform-specific package; alpine/musl targets where sharp's glibc binary will not load; yarn/npm workspaces hoisting sharp away from the expected path.

Related errors

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/b5eafc6b79def828. Report an issue: GitHub.