Nx fails in CI because its native binary package is missing
Error: Cannot find module '@nx/nx-linux-x64-gnu'Short answer
Nx ships its native code as a separate package per OS and CPU, installed as an optional dependency. The error means the package for this machine was not installed: optional dependencies were skipped, npm left it out of package-lock.json, or Node runs for the wrong architecture. Reinstall with optionals on, regenerate the lockfile, then check nx report.
Fix it fast
1Find out which cause you have
Check whether a native package exists in node_modules and which platform Node reports. A missing folder means the install skipped it; a platform that does not match the machine points to the Node architecture.
ls node_modules/@nx | grep "^nx-" node -p "process.platform + '-' + process.arch"2Match what you see, then jump to its fix
- 1
The CI log shows npm install --omit=optional or a similar flagThe install ran without optional dependenciesFix - 2
npm ci succeeds but node_modules/@nx has no nx-linux-x64-gnu, often after the lockfile was made on macOS or Windowspackage-lock.json was written without the Nx platform packageFix - 3
nx report shows x64 on an arm64 machine, or the reverseNode.js is installed for the wrong CPU architectureFix
- 1
What does the error look like?
Error: Cannot find module '@nx/nx-linux-x64-gnu'Nx cannot find a @nx/nx-platform moduleYour platform is not supported
Cause 1 of 3
The install ran without optional dependencies
1Check
npm skips optionalDependencies when told to. Look for the flag in workflow files, Dockerfiles and npm config.
grep -rn -E "omit=optional|no-optional" .github Dockerfile* package.json 2>/dev/null
npm config get omit2Fix
Remove the flag so the platform package is installed. If you must omit some types, include optional ones explicitly.
npm ci --include=optional3Verify
The platform folder now exists.
ls node_modules/@nx | grep "^nx-"Confirmed by docs.npmjs.com
Cause 2 of 3
package-lock.json was written without the Nx platform package
1Check
Nx's troubleshooting page says npm sometimes fails to record the optional packages Nx needs in the lockfile. Search the lockfile for the one your CI needs.
grep -c "@nx/nx-linux-x64-gnu" package-lock.json2Fix
Delete node_modules and the lockfile, install again, and commit the new lockfile.
rm -rf node_modules package-lock.json
npm install3Verify
The lockfile now lists the Linux package, and a clean CI-style install works.
grep -c "@nx/nx-linux-x64-gnu" package-lock.json
npm ciConfirmed by canary.nx.dev
Cause 3 of 3
Node.js is installed for the wrong CPU architecture
1Check
Nx names the package after the platform and CPU. An x64 Node build on an arm64 chip (or the reverse) asks for a package that does not match the hardware.
npx nx report
node -p "process.arch"2Fix
Reinstall Node.js, and any tool that bundles it, for the real architecture of the machine, then run nx report again.
npx nx report3Verify
The OS line in nx report now matches the chip, for example darwin-arm64 on Apple silicon.
npx nx report | grep -i "OS"Confirmed by canary.nx.dev
How do I stop it coming back?
- Do not pass --omit=optional or --no-optional in install steps.
- Regenerate the lockfile if you move between macOS, Windows and Linux builds and CI starts failing.
- Use npm ci in CI so a stale lockfile fails loudly.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Web apps
Vite will not start because Rollup's native package is missing
npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828)
Rollup ships its compiler as a separate package for each OS and CPU.
3 causes, each with a fixServers
Azure App Service on Linux restarts the container and the site never starts
The container restarts again and again and the site returns an application error
App Service sends a warmup request to the container and restarts it if no HTTP answer comes back in time.
5 causes, each with a fixServers
Cypress says the npm package is installed but the binary is missing
Cypress binary is missing after npm install in CI or in a Docker build
The npm package is only a launcher.
3 causes, each with a fixServers
A native Node.js module fails on AWS Lambda with invalid ELF header
Error: /var/task/node_modules/<package>/build/Release/<name>.node: invalid ELF header
Lambda loads native addons on Linux, so a .node file built on macOS or Windows is not a valid Linux ELF file there.
3 causes, each with a fixServers
nginx 502 Bad Gateway in front of a Node.js app
connect() failed (111: Connection refused) while connecting to upstream
A 502 means nginx reached for your Node.js app and got nothing usable back.
5 causes, each with a fixServers
nginx gives up waiting for the app and returns 504
upstream timed out (110: Connection timed out) while reading response header from upstream
nginx returns 504 when the app behind it takes the request but sends nothing back within proxy_read_timeout (60 seconds by default), or when the connection cannot be opened in time.
5 causes, each with a fix