What causes "Failed to find required LMDB binary" in gatsbyjs/gatsby?

Reinstall dependencies cleanly: rm -rf node_modules package-lock.json && npm install.

gatsbyjs/gatsby · error · Error

Failed to find required LMDB binary

Error message

Failed to find required LMDB binary

What it means

After running installMissing for both lmdb and sharp, bundle-webpack checks that it got a truthy lmdbPackageInfo. A falsy result means checkIfNeedToInstallMissingLmdb returned undefined (e.g. it early-returned undefined because lmdb's package.json could not be read, or no optional dependency matched and it returned undefined instead of throwing). Gatsby treats a missing LMDB binary as fatal because the query engine persists state in lmdb.

Source

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

  const functionsTarget = getFunctionsTargetPlatformAndTarget()

  const dynamicAliases: Record<string, string> = {}
  let forcedLmdbBinaryModule: string | undefined = undefined

  // we need to make sure we have internal packages cache directory setup for current lambda target
  // before we attempt to check if we can reuse those packages
  await createInternalPackagesCacheDir(functionsTarget)

  const [lmdbPackageInfo, sharpPackageInfo] = await installMissing(
    [
      checkIfNeedToInstallMissingLmdb(functionsTarget),
      checkIfNeedToInstallMissingSharp(functionsTarget, currentTarget),
    ],
    functionsTarget
  )

  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})`
      )
    }

View on GitHub (pinned to 8b06340921)

Solutions

Reinstall dependencies cleanly: rm -rf node_modules package-lock.json && npm install.
Clear Gatsby cache: gatsby clean (removes .cache and public).
Verify lmdb is installed and resolvable: node -e "console.log(require.resolve('lmdb'))".
If using a monorepo/hoisting, ensure lmdb is resolvable from the gatsby package's context (add an override/resolution if needed).

Example fix

# before - corrupted install triggers the throw
# after
gatsby clean
rm -rf node_modules package-lock.json
npm install
gatsby build

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight: ensure lmdb resolves and its package.json is readable.
function preflightLmdb() {
  try {
    const path = require.resolve('lmdb')
    require('fs').readFileSync(require('path').join(require('path').dirname(path), 'package.json'), 'utf8')
    return true
  } catch {
    return false
  }
}
if (!preflightLmdb()) throw new Error('lmdb not properly installed; run npm ci')

Type guard

function lmdbInstalled() {
  try { require.resolve('lmdb'); return true } catch { return false }
}

Prevention

Do not prune optionalDependencies in CI caches.
Run npm ci from a clean lockfile in the build environment.
Verify require.resolve('lmdb') works before building.

When it happens

Trigger: installMissing returns [undefined, sharpInfo] for lmdb - i.e. checkIfNeedToInstallMissingLmdb returned undefined rather than a usable info object. Happens when lmdb's package.json cannot be resolved/read (caught and returns undefined) or the binary resolution path silently fails.

Common situations: Broken/incomplete node_modules (lmdb not properly installed or its package.json missing after a partial install); corrupted .cache; CI caching that stripped native package files; an npm/pnpm hoisting layout where require.resolve('lmdb') points somewhere unexpected.

Related errors

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