evanw/esbuild · critical · Error

Unsupported platform: ${platformKey}

Error message

Unsupported platform: ${platformKey}

What it means

`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.

Source

Thrown at lib/npm/node-platform.ts:80

  if (platformKey in knownWindowsPackages) {
    pkg = knownWindowsPackages[platformKey]
    subpath = 'esbuild.exe'
  }

  else if (platformKey in knownUnixlikePackages) {
    pkg = knownUnixlikePackages[platformKey]
    subpath = 'bin/esbuild'
  }

  else if (platformKey in knownWebAssemblyFallbackPackages) {
    pkg = knownWebAssemblyFallbackPackages[platformKey]
    subpath = 'bin/esbuild'
    isWASM = true
  }

  else {
    throw new Error(`Unsupported platform: ${platformKey}`)
  }

  return { pkg, subpath, isWASM }
}

function pkgForSomeOtherPlatform(): string | null {
  const libMainJS = require.resolve('esbuild')
  const nodeModulesDirectory = path.dirname(path.dirname(path.dirname(libMainJS)))

  if (path.basename(nodeModulesDirectory) === 'node_modules') {
    for (const unixKey in knownUnixlikePackages) {
      try {
        const pkg = knownUnixlikePackages[unixKey]
        if (fs.existsSync(path.join(nodeModulesDirectory, pkg))) return pkg
      } catch {
      }
    }

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

1. Switch to `esbuild-wasm`, which runs on any platform that supports WebAssembly.
2. Build esbuild from source for your platform and set `ESBUILD_BINARY_PATH` to the resulting executable.
3. Run the build inside Docker with a supported platform (e.g. `linux x64 LE`).
4. Check the esbuild release notes / GitHub issues for upcoming support of your platform and pin a version that adds it.
5. If you're a downstream packager, contribute a new entry to the known-packages maps and publish the matching binary package.

Example fix

# before
npm install esbuild  # fails on Unsupported platform: linux riscv64 LE

# after
npm install esbuild-wasm
# or
export ESBUILD_BINARY_PATH=/usr/local/bin/esbuild  # self-built

import os from 'os'
const supported = new Set([
  'win32 arm64 LE','win32 ia32 LE','win32 x64 LE',
  'linux x64 LE','linux arm64 LE','linux arm LE','linux ia32 LE',
  'darwin x64 LE','darwin arm64 LE',
  /* ... full knownUnixlikePackages keys */
])
function isSupportedPlatform(): boolean {
  return supported.has(`${process.platform} ${os.arch()} ${os.endianness()}`)
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The "esbuild" package cannot be installed because ${os} is t
• Expected ${JSON.stringify(packageJSON.version)} but got ${JS
• You installed esbuild for another platform than the one you
• Invalid gzip data in archive: ${err && err.message || err}
• Could not find ${JSON.stringify(subpath)} in archive

AI-assisted analysis of evanw/esbuild@6ff1d8b0d8 (2026-08-03). Data as JSON: /data/errors/03940046709103e1.json. Report an issue: GitHub.