Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Nx fails in CI because its native binary package is missing

ErrorError: 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.

  • Applies to Nx 21, Node.js 22, npm 10, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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"
  2. 2Match what you see, then jump to its fix

    1. 1The CI log shows npm install --omit=optional or a similar flagThe install ran without optional dependenciesFix
    2. 2npm 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. 3nx report shows x64 on an arm64 machine, or the reverseNode.js is installed for the wrong CPU architectureFix

What does the error look like?

  • Error: Cannot find module '@nx/nx-linux-x64-gnu'
  • Nx cannot find a @nx/nx-platform module
  • Your 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 omit

2Fix

Remove the flag so the platform package is installed. If you must omit some types, include optional ones explicitly.

npm ci --include=optional

3Verify

The platform folder now exists.

ls node_modules/@nx | grep "^nx-"

Confirmed by docs.npmjs.com

Did this fix it?

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.json

2Fix

Delete node_modules and the lockfile, install again, and commit the new lockfile.

rm -rf node_modules package-lock.json
npm install

3Verify

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 ci

Confirmed by canary.nx.dev

Did this fix it?

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 report

3Verify

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

Did this fix it?

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

Servers

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.