esbuild "Cannot find module @esbuild/linux-x64" - Fix Platform Binary in CI

esbuild installs a platform-specific binary as an optional dependency (e.g. @esbuild/linux-x64). When node_modules is copied across platforms or optional deps are skipped, that package is missing and esbuild cannot run.

What this error means

A build using esbuild (directly, or via Vite/tsup) fails with "Cannot find module '@esbuild/linux-x64'" or a message that the installed esbuild binary version does not match the host. Typical after copying node_modules from a Mac/Windows host into a Linux container.

Build output

Error: Cannot find module '@esbuild/linux-x64'
Require stack:
- /app/node_modules/esbuild/lib/main.js
# or:
Error: Expected "0.21.5" but got "0.20.2" (host version mismatch)

Common causes

node_modules copied across platforms

esbuild’s native binary is platform-scoped. A node_modules installed on one OS/arch lacks the @esbuild/<platform> package the target needs.

Optional dependencies were not installed

The platform binary is an optional dependency. Installing with optional deps omitted (or a misbehaving lockfile) leaves esbuild without its binary.

esbuild and its binary version drifted

A partial update can leave the esbuild JS at one version and the platform binary at another, causing the host-version-mismatch error.

How to fix it

Reinstall on the target platform with optional deps

Do a clean install inside the runtime platform so the right @esbuild/<platform> package is fetched.

Terminal

rm -rf node_modules package-lock.json
npm install            # in the target OS/arch, optional deps enabled
# CI:
npm ci --include=optional

Fix version drift

Ensure esbuild and @esbuild/<platform> are the same version (regenerate the lockfile).
Set the Docker build platform to match runtime.
Avoid mounting/copying a host node_modules into the image.

How to prevent it

Install esbuild on the platform that runs it.
Keep optional dependencies enabled in CI/Docker.
Regenerate the lockfile after esbuild upgrades.