L’erreur « Cannot find native binding »

Le 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, le moteur de compilation de Vite 8, est écrit en Rust. Il est livré sous forme d’un binaire par système : un pour macOS sur puce Apple, un pour Linux x64, et ainsi de suite. npm n’installe que celui de la machine, en le traitant comme une dépendance optionnelle. Le message dit simplement que ce binaire est absent de node_modules. Il ne dit pas pourquoi, et il y a deux raisons possibles.

Savoir laquelle vous touche

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

Cause 1 : Node est trop ancien

Le binaire Linux de rolldown déclare lui-même la version de Node qu’il accepte : ^20.19.0 || >=22.12.0. Sous Node 22.11, npm constate qu’il ne convient pas et, puisque c’est une dépendance optionnelle, il la saute. Sans erreur, sans même un avertissement à son nom. Il faut le mode le plus bavard de npm pour le voir.

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

pluginutils

Le dossier @rolldown ne contient que pluginutils : aucun binaire. Sous Node 22.12, avec le même projet et le même verrou, on y trouve binding-linux-x64-gnu et la compilation passe. Le seul indice visible pendant l’installation est un avertissement EBADENGINE au nom de rolldown et de vite, qui défile bien avant l’erreur.

C’est ici que le conseil du message égare. Nous l’avons suivi à la lettre sous Node 22.11 : suppression du verrou et de node_modules, puis 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.

Même erreur, mot pour mot. La correction est ailleurs : déclarer une version suffisante dans le projet. Les versions testées une à une, et la façon de la déclarer chez chaque hébergeur, sont dans notre guide sur l’erreur « styleText », qui touche les versions encore plus anciennes.

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

Cause 2 : le verrou ne connaît pas le binaire Linux

C’est le défaut de npm que cite le message, ouvert en 2022. Dans certaines conditions, un package-lock.json fabriqué sur un Mac n’enregistre que le binaire macOS. npm ci, qui installe exactement ce que dit le verrou, n’a alors rien à installer pour Linux.

Nous avons reproduit cet état en retirant du verrou les entrées des binaires non macOS, puis compilé sous Node 22.14, une version suffisante. Seul le binaire manque : le message est le même.

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.

Ici, le conseil du message est le bon. Régénérez le verrou avec un npm récent, qui enregistre les binaires de toutes les plateformes. Celui que nous avons fabriqué sur Mac avec npm 11 en listait quinze, Linux compris, et se compilait sans erreur sous Linux.

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

Si vous ne pouvez pas régénérer le verrou, n’envoyez pas de verrou du tout : le serveur résoudra les dépendances lui-même, sous Linux.