evanw/esbuild · error · Error

You installed esbuild for another platform than the one…

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

In generateBinPath (lib/npm/node-platform.ts:128), when the current platform's package cannot be resolved, the downloaded fallback is absent, and require.resolve(pkg) fails, esbuild checks pkgForSomeOtherPlatform() which scans node_modules for any OTHER @esbuild/* platform package. If one is found, it concludes node_modules was built elsewhere and copied here, and throws this detailed message (lib/npm/node-platform.ts:198) explaining that a native, platform-specific binary cannot run cross-platform. A special Rosetta-2-specific sub-message is used for the darwin x64/arm64 mismatch case.

Solutions

1. Do not copy node_modules across platforms; run `npm ci` / `npm install` inside the target environment.
2. For Docker, copy package.json + lockfile and run the install during image build.
3. With yarn, list both platforms under supportedArchitectures in .yarnrc.yml.
4. For macOS Rosetta 2, install node with the universal installer and reinstall esbuild so both arches resolve.
5. Fall back to esbuild-wasm if a single cross-platform binary is mandatory.

Example fix

# before (Dockerfile)
COPY . /app          # brings host's node_modules (wrong platform)

# after
COPY package.json package-lock.json /app/
RUN npm ci           # install correct platform binaries in-image
COPY . /app

// In a Dockerfile, never copy host node_modules; install in-image.
// (Dockerfile snippet)
// COPY package.json package-lock.json ./
// RUN npm ci
// COPY . .
// Validate at CI start that node_modules was built on this platform:
const fs = require('fs')
const os = require('os')
const expect = `@esbuild/${process.platform}-${os.arch()}`
if (!fs.existsSync(`node_modules/@esbuild/${process.platform}-${os.arch()}`)
    && !fs.existsSync(`node_modules/@esbuild/${process.platform}-${os.arch() === 'x64' ? 'x64' : 'arm64'}`)) {
  console.warn('node_modules may have been built on another platform; run npm ci here')
}

When it happens

Trigger: node_modules containing an esbuild platform binary built for a different OS/arch than the one currently running: e.g. built on macOS/Windows then copied into a Linux Docker image, copied between Windows and WSL, or installed under Rosetta 2 then used natively.

Common situations: Docker builds that COPY a host-built node_modules into the image; WSL <-> Windows sharing of node_modules; installing npm under Rosetta 2 but running node natively (or vice versa); CI artifacts copied across runner OSes.

Related errors

• Unsupported platform
• Expected but got
• Failed to install package
• Missing hash for
• The "esbuild" package cannot be installed because

AI-assisted analysis of evanw/esbuild@f6058f8364 (2026-08-09). Data as JSON: /api/errors/aac3abc5f5412400. Report an issue: GitHub.

Appendix: 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 f6058f8364)