{"record":{"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":"error","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/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/npm/node-platform.ts#L199-L235","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nnpm install esbuild --no-optional --ignore-scripts\n\n# after\nnpm install esbuild                  # allow optionals + scripts\n# or, after the fact:\nnpm rebuild esbuild","handlingStrategy":"validation","validationCode":"// Detect --no-optional/--ignore-scripts style installs and warn before runtime.\nconst fs = require('fs')\nconst os = require('os')\nconst pkg = `@esbuild/${process.platform}-${os.arch()}`\nconst downloaded = `node_modules/esbuild/lib/npm/downloaded-${pkg.replace('/', '-')}-esbuild`\nif (!fs.existsSync(`node_modules/${pkg}`) && !fs.existsSync(downloaded)) {\n  console.error('No esbuild platform binary present. Reinstall without --no-optional/--ignore-scripts, or run: npm rebuild esbuild')\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["install","optional-dependencies","ignore-scripts","platform"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}