{"record":{"id":"41e9bd837853c50e","repo":"evanw/esbuild","slug":"failed-to-install-package-pkg","errorCode":null,"errorMessage":"Failed to install package \"${pkg}\"","messagePattern":"Failed to install package \"(.+?)\"","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"lib/npm/node-install.ts","lineNumber":285,"sourceCode":"  let binPath: string\n  try {\n    // First check for the binary package from our \"optionalDependencies\". This\n    // package should have been installed alongside this package at install time.\n    binPath = require.resolve(`${pkg}/${subpath}`)\n  } catch (e) {\n    console.error(`[esbuild] Failed to find package \"${pkg}\" on the file system\n\nThis can happen if you use the \"--no-optional\" flag. The \"optionalDependencies\"\npackage.json feature is used by esbuild to install the correct binary executable\nfor your current platform. This install script will now attempt to work around\nthis. If that fails, you need to remove the \"--no-optional\" flag to use esbuild.\n`)\n\n    // The \"binary\" in the WebAssembly package is not actually a binary, and is\n    // not self-contained. It's a JavaScript file that references another\n    // binary \"esbuild.wasm\" file. The fallback code below assumes that the\n    // binary is self-contained, so fail now if this is a WebAssembly fallback.\n    if (isWASM) throw new Error(`Failed to install package \"${pkg}\"`)\n\n    // If that didn't work, then someone probably installed esbuild with the\n    // \"--no-optional\" flag. Attempt to compensate for this by downloading the\n    // package using a nested call to \"npm\" instead.\n    //\n    // THIS MAY NOT WORK. Package installation uses \"optionalDependencies\" for\n    // a reason: manually downloading the package has a lot of obscure edge\n    // cases that fail because people have customized their environment in\n    // some strange way that breaks downloading. This code path is just here\n    // to be helpful but it's not the supported way of installing esbuild.\n    binPath = downloadedBinPath(pkg, subpath)\n    try {\n      console.error(`[esbuild] Trying to install package \"${pkg}\" using npm`)\n      installUsingNPM(pkg, subpath, binPath)\n    } catch (e2: any) {\n      console.error(`[esbuild] Failed to install package \"${pkg}\" using npm: ${e2 && e2.message || e2}`)\n\n      // If that didn't also work, then something is likely wrong with the \"npm\"","sourceCodeStart":267,"sourceCodeEnd":303,"githubUrl":"https://github.com/evanw/esbuild/blob/f6058f8364fe7ab91ca57a83e02577ed74c9cae4/lib/npm/node-install.ts#L267-L303","documentation":"In checkAndPreparePackage (lib/npm/node-install.ts:285), when require.resolve(pkg) fails to find the platform package AND the platform is a WebAssembly-fallback platform (isWASM true), esbuild throws immediately. The reason is that the generic download fallback only works for self-contained native binaries; a WASM 'binary' is actually a JS file referencing a separate esbuild.wasm, so the fallback cannot reconstitute it. This is hit on WASM-fallback platforms like android-arm when the optional dependency was skipped.","triggerScenarios":"Installing esbuild on a WASM-fallback platform (e.g. @esbuild/android-arm, android-x64, openharmony-arm64) while the optional @esbuild/* package is absent (installed with --no-optional or --omit=optional).","commonSituations":"Termux/Android development with --no-optional; minimal Docker images that strip optional deps; package managers configured to skip optionals.","solutions":["Remove the --no-optional / --omit=optional flag so the WASM-fallback platform package installs normally.","Explicitly install the required @esbuild/* platform package for your environment.","Switch to the esbuild-wasm package which works without a platform-specific optional dependency."],"exampleFix":"# before\nnpm install esbuild --no-optional   # on a wasm-fallback platform\n\n# after\nnpm install esbuild                 # let optionalDependencies resolve","handlingStrategy":"fallback","validationCode":"// Detect a wasm-fallback platform and avoid --no-optional installs there.\nconst os = require('os')\nconst wasmFallback = new Set([\n  'android arm LE', 'android x64 LE', 'openharmony arm64 LE',\n])\nconst key = `${process.platform} ${os.arch()} ${os.endianness()}`\nif (wasmFallback.has(key)) {\n  console.warn('Use esbuild-wasm or install without --no-optional on this platform')\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Do not install esbuild with --no-optional on WASM-fallback platforms (android, openharmony).","Document esbuild-wasm as the fallback for those environments.","Explicitly install the matching @esbuild/* platform package if optionals are disabled."],"tags":["install","wasm","optional-dependencies","platform"],"backgroundTag":null,"analyzedSha":"f6058f8364fe7ab91ca57a83e02577ed74c9cae4","analyzedAt":"2026-08-09T18:37:22.223Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}