Node "Cannot find module 'lightningcss.linux-x64-gnu.node'" in CI

lightningcss ships its native engine as platform-specific optional dependencies. The Linux x64 binary is missing because optional deps were skipped or the lockfile was generated on another OS.

What this error means

A build using Tailwind v4 or Vite fails with "Cannot find module 'lightningcss.linux-x64-gnu.node'". It works on macOS locally because the darwin binary was installed there.

node

Error: Cannot find module '../lightningcss.linux-x64-gnu.node'
Require stack:
- /work/repo/node_modules/lightningcss/node/index.js

Common causes

Optional dependencies were skipped

An install with --no-optional, or a lockfile lacking the Linux variant, leaves the platform binary uninstalled.

Lockfile generated on a different OS

A committed lockfile that only recorded the macOS/Windows binary omits the Linux entry CI needs.

How to fix it

Install optional dependencies

Allow optional deps so the platform-specific binary is fetched.

Terminal

npm ci --include=optional
# never use --no-optional / omit=optional for these packages

Regenerate the lockfile across platforms

Update the lockfile so it records the Linux variant too.

Delete node_modules and the lockfile locally.
Run npm install to capture all platform optional deps.
Commit the regenerated lockfile.

How to prevent it

Keep optional dependencies enabled in CI.
Generate lockfiles that include all target-platform binaries.
Latchkey self-healing managed runners auto-retry transient optional-binary download failures and cache platform binaries so the right native engine is present.