esbuild "you installed esbuild for another platform" - Optional Deps in CI

esbuild ships a platform-specific native binary as an optional dependency chosen at install time. When node_modules was installed on one OS/arch (or with optional deps skipped) and runs on another, the binary does not match and esbuild refuses to run.

What this error means

The build fails immediately with you installed esbuild for another platform than the one you're currently using, or Host version "x" does not match binary version "y". It is tied to where/how node_modules was created.

Error: You installed esbuild for another platform than the one you're currently using.
Specifically the "@esbuild/darwin-arm64" package is present but this platform
needs the "@esbuild/linux-x64" package instead.

Common causes

node_modules cached or committed cross-platform

A node_modules built on macOS/Windows was committed, or a CI cache from a different OS/arch was restored, so the wrong @esbuild/<os>-<arch> optional package is present.

Optional dependencies skipped at install

Installing with --no-optional (or a lockfile that omits the platform package) leaves esbuild without the binary for the current platform.

How to fix it

Reinstall on the target platform

Delete the foreign node_modules and install fresh so npm fetches the correct optional binary.

rm -rf node_modules
npm ci   # installs the platform-correct @esbuild/<os>-<arch> package

Stop caching node_modules across platforms

1. Never commit node_modules; add it to .gitignore.
2. Key any node_modules cache on the runner OS/arch, or cache ~/.npm and run npm ci.
3. Do not install with --no-optional - esbuild's binary is an optional dependency.

How to prevent it

• Never commit node_modules; install on the runner with npm ci.
• Scope dependency caches to the runner OS/arch.
• Avoid --no-optional so platform binaries are installed.

Related guides