{"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/6ff1d8b0d8c134e867a397eef39702a223ebef9e/lib/npm/node-install.ts#L267-L303","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install without `--no-optional` / `--omit=optional` so the WASM fallback optional package installs normally.","Switch to the `esbuild-wasm` package directly, which bundles the wasm and avoids the platform optionalDependency entirely.","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.","Pin an esbuild version that publishes the WASM fallback package for your platform."],"exampleFix":"# before (Termux / Android)\nnpm install --no-optional esbuild\n# -> Failed to install package \"@esbuild/android-arm\"\n\n# after\nnpm install esbuild-wasm  # platform-independent wasm","handlingStrategy":"fallback","validationCode":"import os from 'os'\nfunction isWasmFallbackPlatform(): boolean {\n  const key = `${process.platform} ${os.arch()} ${os.endianness()}`\n  return [\n    'android arm LE', 'android x64 LE', 'openharmony arm64 LE',\n  ].includes(key)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Don't pass --no-optional on WASM-fallback platforms.","Prefer esbuild-wasm on Android/OpenHarmony.","Document platform support in your project's setup guide.","Run builds in a Docker linux-x64 container if the host is unsupported."],"tags":["install","wasm-fallback","android","optional-dependencies","unsupported-platform"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}