Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js cannot find the compiled .node file of a native module

ErrorError: Could not load the bindings file. Tried:

Short answer

The package needs a compiled .node addon, and none was found in the folders it searches. The usual reasons are install scripts that never ran, a Node.js version change since the install, or a platform that has no prebuilt binary. Print err.tries to see the searched paths, then run npm rebuild or use a supported platform.

  • Applies to Node.js 22, Node.js 24, npm 10, npm 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    The bindings package attaches the list of searched paths to the error. Print it and compare it with what really exists in the module's build folder. Replace your_addon with the addon's name.

    node -e "try { require('bindings')('your_addon') } catch (e) { console.log(e.tries) }"
    find node_modules -name "*.node" -not -path "*/node_modules/*/node_modules/*" | head
  2. 2Match what you see, then jump to its fix

    1. 1No .node file exists under the package; the install used --ignore-scripts or a CI setting that disables scriptsInstall scripts were skipped, so nothing was builtFix
    2. 2It worked before an upgrade or a version-manager switch, and a different Node.js now runs the appNode.js was upgraded or switched after the packages were installedFix
    3. 3Cannot find module '../build/Release/canvas' on a platform that the package does not ship binaries forNo prebuilt binary exists for this operating system or CPU (canvas)Fix

What does the error look like?

  • Error: Could not load the bindings file. Tried:
  • Error: Cannot find module '../build/Release/canvas'

Cause 1 of 3

Install scripts were skipped, so nothing was built

1Check

npm does not run package scripts when ignore-scripts is true, and a native addon is built or fetched by its install script.

npm config get ignore-scripts
grep -n "ignore-scripts" .npmrc ~/.npmrc 2>/dev/null

2Fix

Run the lifecycle scripts again with rebuild, with ignore-scripts overridden to false. Foreground scripts show the build output.

npm rebuild --ignore-scripts=false --foreground-scripts

3Verify

A .node file now exists and the module loads.

find node_modules -name "*.node" | head
node -e "require('canvas'); console.log('ok')"

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

Node.js was upgraded or switched after the packages were installed

1Check

Compiled addons are tied to the Node.js version they were built for. The npm documentation names installing a new Node.js version as the case where you recompile all C++ addons.

node -v && npm ls canvas

2Fix

Rebuild every native package with the Node.js you run, or delete node_modules and install again.

npm rebuild
# or
rm -rf node_modules && npm ci

3Verify

Start the app with the same Node.js that ran the rebuild.

node -e "console.log(process.version)" && node app.js

Confirmed by docs.npmjs.com

Did this fix it?

Cause 3 of 3

No prebuilt binary exists for this operating system or CPU (canvas)

1Check

The canvas README lists prebuilt binaries for macOS x64 and arm64, Linux x64, x86 and arm64 (glibc or musl), Linux arm and riscv64 (glibc only) and Windows x64, x86 and arm64.

node -p "process.platform + ' ' + process.arch"

2Fix

Run the app on a listed platform. For an unlisted system, the README (current v4 pre-release) says to go into the package folder and run zig build, and notes you may need to adjust build.zig.

cd node_modules/canvas
zig build

3Verify

The package loads on that machine.

node -e "require('canvas'); console.log('ok')"

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Run npm ci or npm rebuild after every Node.js version change, in development and in CI.
  • Build the production image with the same Node.js version and platform that runs it, not by copying node_modules from a laptop.
  • Keep ignore-scripts off for packages that compile or download a native addon.

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

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

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