evanw/esbuild · error · Error

The package " " could not be found, and is needed by…

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

In generateBinPath (lib/npm/node-platform.ts:217), if the current platform's @esbuild/* package cannot be resolved, the downloaded fallback is missing, require.resolve(pkg) fails, AND pkgForSomeOtherPlatform() also finds nothing, esbuild throws this. The code comment ties this to installing with BOTH --no-optional (so the platform package is absent) and --ignore-scripts (so the postinstall download fallback never ran). There is simply no platform binary available.

Solutions

Drop --no-optional and --ignore-scripts for the esbuild install.
Run `npm rebuild esbuild` (or pnpm rebuild) so the postinstall fetches the binary.
Pre-place the correct @esbuild/* platform package manually.
Use esbuild-wasm which has no platform-specific native dependency.

Example fix

# before
npm install esbuild --no-optional --ignore-scripts

# after
npm install esbuild                  # allow optionals + scripts
# or, after the fact:
npm rebuild esbuild

Defensive patterns

Strategy: validation

Validate before calling

// Detect --no-optional/--ignore-scripts style installs and warn before runtime.
const fs = require('fs')
const os = require('os')
const pkg = `@esbuild/${process.platform}-${os.arch()}`
const downloaded = `node_modules/esbuild/lib/npm/downloaded-${pkg.replace('/', '-')}-esbuild`
if (!fs.existsSync(`node_modules/${pkg}`) && !fs.existsSync(downloaded)) {
  console.error('No esbuild platform binary present. Reinstall without --no-optional/--ignore-scripts, or run: npm rebuild esbuild')
}

Prevention

Do not combine --no-optional with --ignore-scripts when installing esbuild.
Run `npm rebuild esbuild` after such installs to fetch the platform binary.
Prefer esbuild-wasm in environments where scripts are disabled for security.

When it happens

Trigger: Installing esbuild with --no-optional --ignore-scripts (or an equivalent config) so neither the platform optional dependency nor the compensating download script ran, leaving node_modules with no @esbuild/* binary at all.

Common situations: CI/Docker pinning --ignore-scripts for safety; pnpm/npm configs that drop optional deps; security-hardened installs that disable scripts; lockfiles generated with those flags.

Related errors

AI-assisted analysis of evanw/esbuild@f6058f8364 (2026-08-09). Data as JSON: /api/errors/33b8d08e1c99544d. Report an issue: GitHub.

Appendix: 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 f6058f8364)