{"record":{"id":"b5eafc6b79def828","repo":"gatsbyjs/gatsby","slug":"failed-to-locate-or-install-sharp-binary-for-funct","errorCode":null,"errorMessage":"Failed to locate or install Sharp binary for functions execution platform/arch (${functionsTarget.platform}/${functionsTarget.arch})","messagePattern":"Failed to locate or install Sharp binary for functions execution platform/arch \\((.+?)/(.+?)\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/gatsby/src/schema/graphql-engine/bundle-webpack.ts","lineNumber":397,"sourceCode":"  )\n\n  if (!lmdbPackageInfo) {\n    throw new Error(`Failed to find required LMDB binary`)\n  } else if (functionsTarget.platform === `linux`) {\n    // function execution platform is primarily linux, which is tested the most, so we only force that specific binary\n    // to not cause untested code paths\n    if (lmdbPackageInfo.needToInstall) {\n      throw new Error(\n        `Failed to locate or install LMDB binary for functions execution platform/arch (${functionsTarget.platform}/${functionsTarget.arch})`\n      )\n    }\n\n    forcedLmdbBinaryModule = `${lmdbPackageInfo.packageLocation}/node.abi83.glibc.node`\n  }\n\n  if (sharpPackageInfo) {\n    if (sharpPackageInfo.needToInstall) {\n      throw new Error(\n        `Failed to locate or install Sharp binary for functions execution platform/arch (${functionsTarget.platform}/${functionsTarget.arch})`\n      )\n    }\n    dynamicAliases[`sharp$`] = sharpPackageInfo.packageLocation\n  }\n\n  const compiler = webpack({\n    name: `Query Engine`,\n    // mode: `production`,\n    mode: `none`,\n    entry: path.join(__dirname, `entry.js`),\n    output: {\n      path: outputDir,\n      filename: `index.js`,\n      libraryTarget: `commonjs`,\n    },\n    target: `node`,\n    externalsPresets: {","sourceCodeStart":379,"sourceCodeEnd":415,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/8b06340921ffdf23125a365b9c9923690cb62ce6/packages/gatsby/src/schema/graphql-engine/bundle-webpack.ts#L379-L415","documentation":"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$'].","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before - sharp linux binary missing when cross-building\n# after\ndocker run --rm -v \"$PWD\":/srv -w /srv node:18 bash -lc \"npm ci && gatsby build --functions-platform=linux --functions-arch=x64\"","handlingStrategy":"validation","validationCode":"// Pre-check sharp's binary for the target is on disk.\nfunction sharpBinaryPresent() {\n  try {\n    const dir = path.join(path.dirname(require.resolve('sharp')), '..', 'build', 'Release')\n    return fs.existsSync(dir) && fs.readdirSync(dir).some(f => f.endsWith('.node'))\n  } catch { return false }\n}","typeGuard":"function hasFunctionsTarget(t) { return !!t?.platform && !!t?.arch }","tryCatchPattern":null,"preventionTips":["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."],"tags":["bundle-webpack","sharp","functions","native-binary","cross-compile"],"backgroundTag":null,"analyzedSha":"8b06340921ffdf23125a365b9c9923690cb62ce6","analyzedAt":"2026-08-13T02:36:21.405Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}