The “Cannot find native binding” error

The message

Error: Cannot find native binding. npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). Please try `npm i` again after removing both package-lock.json and node_modules directory.
    at file:///app/node_modules/rolldown/dist/shared/binding-BbrDfv1x.mjs:602:34
    at file:///app/node_modules/rolldown/dist/shared/binding-BbrDfv1x.mjs:9:49

rolldown, the bundler behind Vite 8, is written in Rust. It ships as one binary per system: one for macOS on Apple silicon, one for Linux x64, and so on. npm only installs the one for the current machine, treating it as an optional dependency. The message simply says this binary is missing from node_modules. It does not say why, and there are two possible reasons.

Find out which one affects you

node -v
grep -c '"node_modules/@rolldown/binding-linux-x64-gnu"' package-lock.json

Cause 1: Node is too old

Rolldown’s Linux binary declares the Node versions it accepts: ^20.19.0 || >=22.12.0. On Node 22.11, npm sees that it does not fit and, since it is an optional dependency, skips it. No error, not even a warning in its name. You need npm’s most verbose mode to see it.

npm verbose reify failed optional dependency /app/node_modules/@rolldown/binding-linux-x64-gnu

pluginutils

The @rolldown folder only holds pluginutils: no binary. On Node 22.12, with the same project and the same lockfile, it holds binding-linux-x64-gnu and the build succeeds. The only visible clue during the install is an EBADENGINE warning for rolldown and vite, which scrolls past long before the error.

This is where the message’s advice misleads. We followed it to the letter on Node 22.11: delete the lockfile and node_modules, then npm i.

npm warn EBADENGINE   package: '@vitejs/plugin-react@6.1.1',
npm warn EBADENGINE   package: 'vite@8.3.0',
npm warn EBADENGINE   package: 'oxlint@1.85.0',
npm warn EBADENGINE   package: 'rolldown@1.2.9',

Error: Cannot find native binding. npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). Please try `npm i` again after removing both package-lock.json and node_modules directory.

Same error, word for word. The fix is elsewhere: declare a sufficient version in the project. The versions tested one by one, and how to set it at each host, are in our guide to the “styleText” error, which hits even older versions.

{
  "engines": {
    "node": ">=22.12"
  }
}

Cause 2: the lockfile does not know the Linux binary

This is the npm bug the message quotes, open since 2022. Under some conditions, a package-lock.json made on a Mac only records the macOS binary. npm ci, which installs exactly what the lockfile says, then has nothing to install for Linux.

We reproduced that state by removing the non-macOS binary entries from the lockfile, then building on Node 22.14, a sufficient version. Only the binary is missing: the message is the same.

Error: Cannot find native binding. npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). Please try `npm i` again after removing both package-lock.json and node_modules directory.

Here, the message’s advice is right. Regenerate the lockfile with a recent npm, which records the binaries for every platform. The one we made on a Mac with npm 11 listed fifteen of them, Linux included, and built without errors on Linux.

rm -rf node_modules package-lock.json
npm i
grep -c '"node_modules/@rolldown/binding-linux-x64-gnu"' package-lock.json

If you cannot regenerate the lockfile, do not ship one at all: the server will resolve the dependencies itself, on Linux.