evanw/esbuild · error · Error

Failed to install package "${pkg}"

Error message

Failed to install package "${pkg}"

What it means

In `checkAndPreparePackage` (`node-install.ts:285`), when the optional package isn't on disk, esbuild tries the fallback installers. If the current platform's package is a WASM fallback (e.g. `@esbuild/android-arm`), the install bails immediately because the WASM binary isn't self-contained and the fallback download path doesn't support it. The thrown message wraps this case.

Source

Thrown at lib/npm/node-install.ts:285

  let binPath: string
  try {
    // First check for the binary package from our "optionalDependencies". This
    // package should have been installed alongside this package at install time.
    binPath = require.resolve(`${pkg}/${subpath}`)
  } catch (e) {
    console.error(`[esbuild] Failed to find package "${pkg}" on the file system

This can happen if you use the "--no-optional" flag. The "optionalDependencies"
package.json feature is used by esbuild to install the correct binary executable
for your current platform. This install script will now attempt to work around
this. If that fails, you need to remove the "--no-optional" flag to use esbuild.
`)

    // The "binary" in the WebAssembly package is not actually a binary, and is
    // not self-contained. It's a JavaScript file that references another
    // binary "esbuild.wasm" file. The fallback code below assumes that the
    // binary is self-contained, so fail now if this is a WebAssembly fallback.
    if (isWASM) throw new Error(`Failed to install package "${pkg}"`)

    // If that didn't work, then someone probably installed esbuild with the
    // "--no-optional" flag. Attempt to compensate for this by downloading the
    // package using a nested call to "npm" instead.
    //
    // THIS MAY NOT WORK. Package installation uses "optionalDependencies" for
    // a reason: manually downloading the package has a lot of obscure edge
    // cases that fail because people have customized their environment in
    // some strange way that breaks downloading. This code path is just here
    // to be helpful but it's not the supported way of installing esbuild.
    binPath = downloadedBinPath(pkg, subpath)
    try {
      console.error(`[esbuild] Trying to install package "${pkg}" using npm`)
      installUsingNPM(pkg, subpath, binPath)
    } catch (e2: any) {
      console.error(`[esbuild] Failed to install package "${pkg}" using npm: ${e2 && e2.message || e2}`)

      // If that didn't also work, then something is likely wrong with the "npm"

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

1. Install without `--no-optional` / `--omit=optional` so the WASM fallback optional package installs normally.
2. Switch to the `esbuild-wasm` package directly, which bundles the wasm and avoids the platform optionalDependency entirely.
3. Run esbuild in a different environment (Docker with a linux-x64 image, or a remote build server) if your host platform can't provide a working binary.
4. Pin an esbuild version that publishes the WASM fallback package for your platform.

Example fix

# before (Termux / Android)
npm install --no-optional esbuild
# -> Failed to install package "@esbuild/android-arm"

# after
npm install esbuild-wasm  # platform-independent wasm

import os from 'os'
function isWasmFallbackPlatform(): boolean {
  const key = `${process.platform} ${os.arch()} ${os.endianness()}`
  return [
    'android arm LE', 'android x64 LE', 'openharmony arm64 LE',
  ].includes(key)
}

When it happens

Trigger: Platform resolves to a `knownWebAssemblyFallbackPackages` entry (android-arm, android-x64, openharmony-arm64), the optional package is missing, and the install cannot use the standard download fallback because the WASM binary requires the accompanying `.wasm` file.

Common situations: Running on Android Termux or OpenHarmony where the platform package didn't install; using `--no-optional` on a WASM-fallback platform; package manager that strips optional deps on exotic platforms.

Related errors

• The package "${pkg}" could not be found, and is needed by es
• The "esbuild" package cannot be installed because ${os} is t
• Expected ${JSON.stringify(packageJSON.version)} but got ${JS
• Invalid gzip data in archive: ${err && err.message || err}
• Could not find ${JSON.stringify(subpath)} in archive

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