evanw/esbuild · critical · Error

You installed esbuild for another platform than the one you

Error message

You installed esbuild for another platform than the one you're currently using.
This won't work because esbuild is written with native code and needs to
install a platform-specific binary executable.
${suggestions}
Another alternative is to use the "esbuild-wasm" package instead, which works
the same way on all platforms. But it comes with a heavy performance cost and
can sometimes be 10x slower than the "esbuild" package, so you may also not
want to do that.

What it means

`generateBinPath` (`node-platform.ts:198`) throws this when the optional package for the *current* platform is missing, but a package for a *different* platform is found in `node_modules`. esbuild guesses the user copied a `node_modules` tree between platforms (Docker image build, WSL/Windows copy, Rosetta). The message includes platform-specific guidance (Rosetta for darwin x64↔arm64, supportedArchitectures for yarn).

Source

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

situation by installing esbuild with npm running inside of Rosetta 2 and then
trying to use it with node running outside of Rosetta 2, or vice versa (Rosetta
2 is Apple's on-the-fly x86_64-to-arm64 translation service).

If you are installing with npm, you can try ensuring that both npm and node are
not running under Rosetta 2 and then reinstalling esbuild. This likely involves
changing how you installed npm and/or node. For example, installing node with
the universal installer here should work: https://nodejs.org/en/download/. Or
you could consider using yarn instead of npm which has built-in support for
installing a package on multiple platforms simultaneously.

If you are installing with yarn, you can try listing both "arm64" and "x64"
in your ".yarnrc.yml" file using the "supportedArchitectures" feature:
https://yarnpkg.com/configuration/yarnrc/#supportedArchitectures
Keep in mind that this means multiple copies of esbuild will be present.
`
          }

          throw new Error(`
You installed esbuild for another platform than the one you're currently using.
This won't work because esbuild is written with native code and needs to
install a platform-specific binary executable.
${suggestions}
Another alternative is to use the "esbuild-wasm" package instead, which works
the same way on all platforms. But it comes with a heavy performance cost and
can sometimes be 10x slower than the "esbuild" package, so you may also not
want to do that.
`)
        }

        // If that didn't work too, then maybe someone installed esbuild with
        // both the "--no-optional" and the "--ignore-scripts" flags. The fix
        // for this is to just not do that. We don't attempt to handle this
        // case at all.
        //
        // In that case we try to have a nice error message if we think we know
        // what's happening. Otherwise we just rethrow the original error message.

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

Don't copy `node_modules` across platforms: run `npm ci` on the destination platform (e.g. inside the final Docker image).
Use a multi-arch Docker build (`docker buildx`) so each platform gets its own `node_modules`.
For yarn, list both architectures under `supportedArchitectures` in `.yarnrc.yml`.
On macOS arm64, ensure both npm and node run natively (not under Rosetta 2) before installing — use the universal node installer.
As a quick workaround, switch to `esbuild-wasm` which is platform-independent.

Example fix

# before (Dockerfile)
FROM node:18 AS build
RUN npm install         # builds linux-x64 deps
FROM --platform=linux/arm64 node:18
COPY --from=build /app/node_modules ./node_modules  # wrong arch!

# after
FROM --platform=linux/arm64 node:18
COPY package*.json ./
RUN npm ci             # rebuilds node_modules for arm64

Defensive patterns

Strategy: validation

Validate before calling

import os from 'os'
const want = `@esbuild/${platformToPkg(process.platform, os.arch(), os.endianness())}`
import { existsSync } from 'fs'
import { dirname } from 'path'
function correctPlatformPackageInstalled(): boolean {
  try { return existsSync(require.resolve(`${want}/bin/esbuild`).replace(/\/bin.*/, '')) }
  catch { return false }
}

Prevention

Never COPY node_modules between Docker stages of different platforms.
Run npm ci on the destination platform after copying source.
For yarn, declare all target platforms under supportedArchitectures.
On macOS arm64 ensure node runs natively (not under Rosetta).
Use multi-arch Docker builds (buildx) instead of copying node_modules.

When it happens

Trigger: Platform-resolved `pkg` not resolvable, but `pkgForSomeOtherPlatform()` finds another `@esbuild/<platform>` directory in `node_modules`. Specifically: building on one OS/arch and copying `node_modules` to another; running under Rosetta 2 mismatch; building in Docker with the wrong base image.

Common situations: Multi-stage Docker builds that `COPY node_modules` from a build stage of a different OS/arch; WSL2 development with `node_modules` shared from Windows; macOS arm64 dev running x64-built dependencies under Rosetta; CI matrix where artifacts leak between jobs.

Related errors

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