evanw/esbuild · critical · Error

The package "${pkg}" could not be found, and is needed by es

Error message

The package "${pkg}" could not be found, and is needed by esbuild.

If you are installing esbuild with npm, make sure that you don't specify the
"--no-optional" or "--omit=optional" flags. The "optionalDependencies" feature
of "package.json" is used by esbuild to install the correct binary executable
for your current platform.

What it means

`generateBinPath` (`node-platform.ts:217`) throws this when the platform package is missing from `node_modules` AND no other-platform package is detected either — typically because the user installed with `--no-optional` and `--ignore-scripts`, so neither the optionalDependency nor the postinstall fallback ran. esbuild has no way to obtain or build the binary.

Source

Thrown at lib/npm/node-platform.ts:217

You installed esbuild for another platform than the one you're currently using.
This won't work because esbuild is written with native code and needs to
install a platform-specific binary executable.
${suggestions}
Another alternative is to use the "esbuild-wasm" package instead, which works
the same way on all platforms. But it comes with a heavy performance cost and
can sometimes be 10x slower than the "esbuild" package, so you may also not
want to do that.
`)
        }

        // If that didn't work too, then maybe someone installed esbuild with
        // both the "--no-optional" and the "--ignore-scripts" flags. The fix
        // for this is to just not do that. We don't attempt to handle this
        // case at all.
        //
        // In that case we try to have a nice error message if we think we know
        // what's happening. Otherwise we just rethrow the original error message.
        throw new Error(`The package "${pkg}" could not be found, and is needed by esbuild.

If you are installing esbuild with npm, make sure that you don't specify the
"--no-optional" or "--omit=optional" flags. The "optionalDependencies" feature
of "package.json" is used by esbuild to install the correct binary executable
for your current platform.`)
      }
      throw e
    }
  }

  // This code below guards against the unlikely case that the user is using
  // Yarn 2+ in PnP mode and that version is old enough that it doesn't support
  // the "preferUnplugged" setting. If that's the case, then the path to the
  // binary executable that we got above isn't actually a real path. Instead
  // it's a path to a zip file with some extra stuff appended to it.
  //
  // Yarn's PnP mode tries hard to patch Node's file system APIs to pretend
  // that these fake paths are real. So we can't check whether it's a real file

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

1. Remove `--no-optional` and `--ignore-scripts` from your install command.
2. If you must skip scripts in CI, omit only `--ignore-scripts` (keep optional deps), or re-enable scripts for the esbuild package only.
3. Pin esbuild in your lockfile so optionalDependencies are tracked.
4. Switch to `esbuild-wasm` if your environment genuinely can't run postinstall scripts.
5. Use `ESBUILD_BINARY_PATH` to point at a separately-installed esbuild binary.

Example fix

# before
npm ci --no-optional --ignore-scripts

# after
npm ci                # optional deps + install scripts allowed
# or scoped:
npm ci --ignore-scripts  # still installs optionalDependencies

import { existsSync } from 'fs'
import os from 'os'
function platformPackagePresent(): boolean {
  const pkg = pickEsbuildPkg(process.platform, os.arch()) // e.g. @esbuild/linux-x64
  try { require.resolve(`${pkg}/bin/esbuild`); return true } catch { return false }
}

When it happens

Trigger: All three of: current-platform `@esbuild/<platform>` package not in node_modules, no other-platform package present, and the `require.resolve(pkg)` itself throws. The most common cause is installing esbuild with both `--no-optional` (or `--omit=optional`) and `--ignore-scripts`.

Common situations: Docker builds / CI with `npm ci --omit=optional --ignore-scripts` to optimize install speed; corporate npm wrapper that strips optional deps; yarn with `enableScripts: false` and `optional-fallback: false` setups; lockfile-only installs that don't fetch optional deps.

Related errors

• Failed to install package "${pkg}"
• The "buildSync" API only works in node
• Must provide either the "wasmURL" option or the "wasmModule"
• The "esbuild" package cannot be installed because ${os} is t
• Expected ${JSON.stringify(packageJSON.version)} but got ${JS

AI-assisted analysis of evanw/esbuild@6ff1d8b0d8 (2026-08-03). Data as JSON: /data/errors/33b8d08e1c99544d.json. Report an issue: GitHub.