{"id":"03940046709103e1","repo":"evanw/esbuild","slug":"unsupported-platform-platformkey","errorCode":null,"errorMessage":"Unsupported platform: ${platformKey}","messagePattern":"Unsupported platform: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"lib/npm/node-platform.ts","lineNumber":80,"sourceCode":"\n  if (platformKey in knownWindowsPackages) {\n    pkg = knownWindowsPackages[platformKey]\n    subpath = 'esbuild.exe'\n  }\n\n  else if (platformKey in knownUnixlikePackages) {\n    pkg = knownUnixlikePackages[platformKey]\n    subpath = 'bin/esbuild'\n  }\n\n  else if (platformKey in knownWebAssemblyFallbackPackages) {\n    pkg = knownWebAssemblyFallbackPackages[platformKey]\n    subpath = 'bin/esbuild'\n    isWASM = true\n  }\n\n  else {\n    throw new Error(`Unsupported platform: ${platformKey}`)\n  }\n\n  return { pkg, subpath, isWASM }\n}\n\nfunction pkgForSomeOtherPlatform(): string | null {\n  const libMainJS = require.resolve('esbuild')\n  const nodeModulesDirectory = path.dirname(path.dirname(path.dirname(libMainJS)))\n\n  if (path.basename(nodeModulesDirectory) === 'node_modules') {\n    for (const unixKey in knownUnixlikePackages) {\n      try {\n        const pkg = knownUnixlikePackages[unixKey]\n        if (fs.existsSync(path.join(nodeModulesDirectory, pkg))) return pkg\n      } catch {\n      }\n    }\n","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/lib/npm/node-platform.ts#L62-L98","documentation":"`pkgAndSubpathForCurrentPlatform` (`node-platform.ts:80`) constructs `platformKey = \"${process.platform} ${os.arch()} ${os.endianness()}\"` and looks it up in `knownWindowsPackages`, `knownUnixlikePackages`, and `knownWebAssemblyFallbackPackages`. If the key matches none, the platform has no published esbuild binary and the function refuses to guess.","triggerScenarios":"Importing esbuild on a platform/arch/endianness combo esbuild doesn't ship a prebuilt binary for — e.g. a new CPU architecture, an unusual OS, or a Node build with a non-standard endianness.","commonSituations":"Running on a brand-new architecture (e.g. early linux-riscv64 before official support); niche OSes (Haiku, Serenity); unusual endianness configurations; using Node on an embedded target; a CI provider rolling out new hardware.","solutions":["Switch to `esbuild-wasm`, which runs on any platform that supports WebAssembly.","Build esbuild from source for your platform and set `ESBUILD_BINARY_PATH` to the resulting executable.","Run the build inside Docker with a supported platform (e.g. `linux x64 LE`).","Check the esbuild release notes / GitHub issues for upcoming support of your platform and pin a version that adds it.","If you're a downstream packager, contribute a new entry to the known-packages maps and publish the matching binary package."],"exampleFix":"# before\nnpm install esbuild  # fails on Unsupported platform: linux riscv64 LE\n\n# after\nnpm install esbuild-wasm\n# or\nexport ESBUILD_BINARY_PATH=/usr/local/bin/esbuild  # self-built","handlingStrategy":"fallback","validationCode":"import os from 'os'\nconst supported = new Set([\n  'win32 arm64 LE','win32 ia32 LE','win32 x64 LE',\n  'linux x64 LE','linux arm64 LE','linux arm LE','linux ia32 LE',\n  'darwin x64 LE','darwin arm64 LE',\n  /* ... full knownUnixlikePackages keys */\n])\nfunction isSupportedPlatform(): boolean {\n  return supported.has(`${process.platform} ${os.arch()} ${os.endianness()}`)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Run builds in a Docker container of a supported platform.","Keep esbuild-wasm available for exotic architectures.","Pre-build esbuild for your platform and set ESBUILD_BINARY_PATH.","Check esbuild release notes for newly added platforms before pinning."],"tags":["platform","architecture","unsupported","install","native-binary"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}