{"id":"33b8d08e1c99544d","repo":"evanw/esbuild","slug":"the-package-pkg-could-not-be-found-and-is-ne","errorCode":null,"errorMessage":"The package \"${pkg}\" could not be found, and is needed by esbuild.\n\nIf you are installing esbuild with npm, make sure that you don't specify the\n\"--no-optional\" or \"--omit=optional\" flags. The \"optionalDependencies\" feature\nof \"package.json\" is used by esbuild to install the correct binary executable\nfor your current platform.","messagePattern":"The package \"(.+?)\" could not be found, and is needed by esbuild\\.\n\nIf you are installing esbuild with npm, make sure that you don't specify the\n\"--no-optional\" or \"--omit=optional\" flags\\. The \"optionalDependencies\" feature\nof \"package\\.json\" is used by esbuild to install the correct binary executable\nfor your current platform\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"lib/npm/node-platform.ts","lineNumber":217,"sourceCode":"You installed esbuild for another platform than the one you're currently using.\nThis won't work because esbuild is written with native code and needs to\ninstall a platform-specific binary executable.\n${suggestions}\nAnother alternative is to use the \"esbuild-wasm\" package instead, which works\nthe same way on all platforms. But it comes with a heavy performance cost and\ncan sometimes be 10x slower than the \"esbuild\" package, so you may also not\nwant to do that.\n`)\n        }\n\n        // If that didn't work too, then maybe someone installed esbuild with\n        // both the \"--no-optional\" and the \"--ignore-scripts\" flags. The fix\n        // for this is to just not do that. We don't attempt to handle this\n        // case at all.\n        //\n        // In that case we try to have a nice error message if we think we know\n        // what's happening. Otherwise we just rethrow the original error message.\n        throw new Error(`The package \"${pkg}\" could not be found, and is needed by esbuild.\n\nIf you are installing esbuild with npm, make sure that you don't specify the\n\"--no-optional\" or \"--omit=optional\" flags. The \"optionalDependencies\" feature\nof \"package.json\" is used by esbuild to install the correct binary executable\nfor your current platform.`)\n      }\n      throw e\n    }\n  }\n\n  // This code below guards against the unlikely case that the user is using\n  // Yarn 2+ in PnP mode and that version is old enough that it doesn't support\n  // the \"preferUnplugged\" setting. If that's the case, then the path to the\n  // binary executable that we got above isn't actually a real path. Instead\n  // it's a path to a zip file with some extra stuff appended to it.\n  //\n  // Yarn's PnP mode tries hard to patch Node's file system APIs to pretend\n  // that these fake paths are real. So we can't check whether it's a real file","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/lib/npm/node-platform.ts#L199-L235","documentation":"`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.","triggerScenarios":"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`.","commonSituations":"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.","solutions":["Remove `--no-optional` and `--ignore-scripts` from your install command.","If you must skip scripts in CI, omit only `--ignore-scripts` (keep optional deps), or re-enable scripts for the esbuild package only.","Pin esbuild in your lockfile so optionalDependencies are tracked.","Switch to `esbuild-wasm` if your environment genuinely can't run postinstall scripts.","Use `ESBUILD_BINARY_PATH` to point at a separately-installed esbuild binary."],"exampleFix":"# before\nnpm ci --no-optional --ignore-scripts\n\n# after\nnpm ci                # optional deps + install scripts allowed\n# or scoped:\nnpm ci --ignore-scripts  # still installs optionalDependencies","handlingStrategy":"validation","validationCode":"import { existsSync } from 'fs'\nimport os from 'os'\nfunction platformPackagePresent(): boolean {\n  const pkg = pickEsbuildPkg(process.platform, os.arch()) // e.g. @esbuild/linux-x64\n  try { require.resolve(`${pkg}/bin/esbuild`); return true } catch { return false }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Don't combine --no-optional with --ignore-scripts.","Re-enable install scripts for at least the esbuild package in CI.","Pin esbuild so optionalDependencies are tracked in the lockfile.","Keep esbuild-wasm as a fallback when postinstall must be disabled."],"tags":["install","optional-dependencies","ignore-scripts","ci","configuration"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}