esbuild "you installed esbuild for another platform" - Fix in CI

By Kaveh Alemi·Latchkey

esbuild ships a platform-specific native binary chosen at install time. When node_modules was installed on one OS/arch (e.g. macOS arm64) and runs on another (Linux x64), 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 consistent and tied to where node_modules was created.

build output

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.
  Specifically the "@esbuild/darwin-arm64" package is present but this platform
  needs the "@esbuild/linux-x64" package instead.

Common causes

node_modules committed or cached cross-platform

A node_modules directory built on a developer's macOS/Windows machine was committed, or a CI cache from a different OS/arch was restored, so the wrong esbuild binary is present.

Optional-deps skipped at install

Installing with --no-optional, or a lockfile that omits the platform binary 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 esbuild fetches the correct binary for the runner.

Terminal

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

Stop caching/committing node_modules across platforms

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

How to prevent it

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

Frequently asked questions

What causes ""esbuild for another platform""?

A node_modules directory built on a developer's macOS/Windows machine was committed, or a CI cache from a different OS/arch was restored, so the wrong esbuild binary is present.

How do I fix "esbuild for another platform"?

Delete the foreign node_modules and install fresh so esbuild fetches the correct binary for the runner.

Can Latchkey fix this automatically?

Yes. Latchkey runs your GitHub Actions on managed runners that detect this failure, apply the fix, and retry the job automatically - self-healing is on by default.